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INTRODUCTION 


This is your CP/M Reference Manual. In it you will find complete instructions for 
using the CP/M operating system on your XEROX 820. 


The CP/M operating system is an industry standard operating system that lets you use 
a variety of programs you can purchase at software houses everywhere. The 
instructions you'll need to load programs can be found in the CP/M Primer as well as 
in this reference manual. 


A brief description of the 820 is given on page 1-5 of this manual. More information 
on the 820's single-board computer and ROM monitor commands are given in the 
SYSTEM COMPONENTS section of this manual (beginning on page 10-23). This 
information will be helpful to you as a programming aid. 


To go along with the reference manual is the CP/M Primer (separate package) that 
you can use to learn the basics of CP/M. As you go through the CP/M Primer, you'll 
notice a few discrepancies between the illustrations in the Primer and what you see 
on your screen. For instance, the illustration may show titles vertically whereas the 
screen displays the titles horizontally. The MAIN difference between what you read 
in the Primer and what you see on the screen is how the messages are displayed. 


To use this manual and the CP/M Primer, you'll need 


@ a Xerox 820 Information Processor (screen, keyboard, and disk drives --the 
printer's, optional), and 


@ aCP/M disk (packaged at the back of this manual), and 


e a blank disk so you can make a backup copy of your CP/M disk. 


We recommend you get the CP/M disk and a blank disk right now and make the 
backup copy of your software. That way, if anybody spills coffee on the disk, you 
still have your software. The instructions on the next page tell you how to prepare a 
disk and copy your software. The instructions are written for both 5%" and 8" disks. 


We also recommend that you always remove your disks from the 820 before you turn 
it off. .Leaving disks in the system when you power down can permanently erase 
information on the disks. 
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HOW TO MAKE BACK UP COPIES OF YOUR DISKS 


— 


id 


The instructions below tell you how to load the CP/M software. Before you can copy 
a disk (or use the 820 to run other programs), you must load CP/M. 


Loading the CP/M software 


OPEN the disk drives (as shown below) and remove any disks 
5%" DISK DRIVES 8" DISK DRIVES 


DRIVE DRIVE DRIVE DRIVE 
A B B 


FOTN 
| fi 


| | 









LOCATE the ON/OFF switch under the right side of the screen (shown below) YS 
TURN the screen on, or press the RESET button if it is already ON 
SCREEN 8" DISK DRIVES 


BRIGHTNESS 
CONTROL 
(under edge of screen) 


~~ 






ON/OFF 
SWITCH 


LOCATE the ON/OFF switch on the left side of the 8" disk drives, if your 
system has them (The 5%" disk drives does not have a ON/OFF switch) 
TURN the 8" disk drives on -- if your system has 8" drives, they must be turned 


on for your system to operate. rd 
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INSERT the CP/M disk in the A (left) drive and CLOSE the drive 
5%" DISK DRIVES 8" DISK DRIVES 





DRIVE 





INSERT DISK 





CLOSE DRIVE 


TYPE A and press RETURN to load CP/M into the 820's memory. 


Initializing a Disk 


Before you can use a new disk in the 820, you must prepare it by initializing it. 
Follow the steps below to use the INIT program to initialize a disk. After you 
initialize the disk, you can copy onto it. 


OBTAIN at least one new disk and take the write protect tape off of the 5%" 
disk, or put a write protect tape on the 8" disk. 
(If you don't have a new disk, a previously used one will do.) 


d%"' DISK 8" DISK 
UP AND IN 
WRITE ARROWS 
PROTECT 
TAPE 
WRITE 
PROTECT 
TAPE 


OVAL 
CUTOUT 
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TYPE the word INIT and press RETURN 


WAIT for the message ENTER DISK DRIVE TO BE INITIALIZED (A OR B) 


INSERT the new disk in drive B, type B and press RETURN twice 


Wait for the message 0 FLAWED SECTORS. (If the disk has flawed 
sectors as indicated by a number other than 0 in front of the FLAWED 
SECTORS message, don't use it to copy your software - get another disk 
and initialize it, using steps below) 


IF you had flawed sectors, initialize another disk as follows: 


@ Remove the disk in the B (right) drive 

Insert another disk in the B drive 

Type B 

Press RETURN twice 

Remove the disk after the FLAWED SECTORS message appears 


WHEN all the disks are initialized: 


@ Press the SPACE bar 
e Wait for A> to appear on the screen, then continue with the steps 
below 


Copying a Disk 


Now that you've initialized a disk, you are ready to copy the CP/M software. 


TYPE the word COPY and press RETURN 


Wait for a message that tells you to insert destination and source disks 


BE SURE your initialized disk is in the B drive 


PRESS the RETURN key 


WAIT for the COPY COMPLETE message 


REMOVE both disks. Put a label on the copy disk that says "CP/M" 


PUT the original disk in the disk holder at the back of this manual 
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Applications Software 
The instructions on page 1-2 and 1-3 told you how to load CP/M. After loading 
CP/M, you can run "applications" programs on the 820. The applications software 
may be purchased from Xerox or from other vendors. 
When you use your CP/M software to run an applications program for the first time, 
the program may ask you to define your system. The following information will help 
you answer these questions. 

Your 820 is configured like a Lear Siegler ADM-3A display terminal. 


Your 820 has two disk drives. The 5%" disks have 40 tracks and will have 81K of 
available space. The 8" disks have 77 tracks and have 241K of available space. 


Your software is a CP/M 2.2 operating system. 


The Typewriter Feature 

If your 820 has a printer, you can use it like a typewriter. Everything you type will 
be printed at the printer, but it will not be recorded on a disk. You do not need to 
have the CP/M software loaded when you use the 820 typewriter feature. 


om REMOVE any disks from the disk drives 
TURN ON your system or press the RESET button if it is already on 
INSERT paper in the printer 
PRESS the T key, then press RETURN 
TYPE just as you would on any typewriter 


As a typewriter, the 820 uses margins of 1 and 65, with tabs set every five spaces. If 
you want to change these settings, use the instructions below. 


SET LEFT MARGIN by pressing the SPACE bar to move to the desired position, 
and pressing ESC then 9 


CLEAR ALL TABS by pressing ESC then 2 


SET A TAB by pressing the SPACE bar to move to the desired position, and 
pressing ESC then Il 


| 
| 
| 
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1. |§ INTRODUCTION, 


CP/M iS a monitor control program for microcomputer system development 
which uses IBM-compatible flexible disks for backup storage, Using a computer 
mainframe based upon Intel’s 80988 microcomputer, CP/M provides a general 
environment for program construction, storage, and editing, along with 
assembly and program check-out facilities, An important feature of CP/M is 
that it can be easily altered to execute with any computer configuration which 
uses an Intel 8880 (or Zilog Z-89) Central Processing Unit, and has at least 
16K bytes of main memory with up to four IBM-compatible diskette drives, A 
detailed discussion of the modifications reguired for any particular hardware 
environment is given in the Digital Research document entitled "CP/M System 
Alteration Guide.” Although the standard Digital Research version operates on 
a sSingle-density Intel MDS 800, several different hardware manufacturers 
Support their own input-output drivers for CP/M. 


The CP/M monitor provides rapid access to programs through a 
comprehensive file management package. The file subsystem supports a named 
file structure, allowing dynamic allocation of file space as well as 
sequential and random file access, Using this file system, a large number of 
distinct programs can be stored in both source and machine executable form, 


CP/M also supports a powerful context editor, Intel-compatible assembler, 
and debugger’ subsystems, Optional software includes a powerful 
Intel-campatible macro assembler, symbolic debugger, along with various 
high-level languages. When coupled with CP/M’s Console Command Processor, the 
resulting facilities equal or excel similar large computer facilities, 


CP/M is logically divided into several distinct parts: 


BIOS Basic I/O System (hardware dependent) 
BDOS BaSic Disk Operating System 

CCP Console Command Processor 

TPA Transient Program Area 


The BIOS provides the primitive operations necessary to access the 
diskette drives and to interface standard peripherals (teletype, CRI, Paper 
Tape Reader/Punch, and user-defined peripherals), and can be tailored by the 
user for any particular hardware environment by "patching" this portion of 
CP/M. The BDOS provides disk management by controlling one or more disk 
drives containing independent file directories. The BDOS implements disk 
allocation strategies which provide fully dynamic file construction while 
minimizing head movement across the disk during access, Any particular file 
may contain any number of records, not exceeding the size of any single disk. 
In a standard CP/M system, each disk can contain up to 64 distinct files, The 


BDOS has entry points which include the following primitive operations which 
can be programmatically accessed: 


SEARCH Look for a particular disk file by name, 

OPEN Open a file for further operations, 

CLOSE Close a file after processing. 

RENAME Change the name of a particular file, 

READ Read a record from a particular file, 

WRITE Write a record onto the disk. 

SELECT Select a particular disk drive for further 
operations, 


The CCP provides symbolic interface between the user’s console and the 
remainder of the CP/M system. The CCP reads the console device and processes 
commands which include listing the file directory, printing the contents of 
files, and controlling the operation of transient programs, such as 
assemblers, editors, and debuggers. The standard commands which are available 
in the CCP are listed in a following section. 


The last segment of CP/M is the area called the Transient Program Area 
(TPA), The TPA holds programs which are loaded from the disk under command of 
the CCP, During program editing, for example, the TPA holds the CP/M text 
editor machine code and data areas, Similarly, programs created under CP/M 
can be checked out by loading and executing these programs in the TPA, 


It should be mentioned that any or all of the ‘CP/M component subsystems 
can be "overlayed" by an executing program. That is, once a user’s program is 
loaded into the TPA, the CCP, BDOS, and BIOS areas can be used as _ the 
program’s data area, A “bootstrap” loader is programmatically accessible 
whenever the BIOS portion is not overlayed; thus, the user program need only 
branch to the bootstrap loader at the end of execution, and the complete CP/M 
monitor is reloaded from disk, 


Tt should be reiterated that the CP/M operating system is partitioned 
into distinct modules, including the BIOS portion which defines the hardware 
environment in which CP/M is executing, fThus, the standard system can be 
easily modified to any non-standard environment by changing the peripheral 
drivers to handle the custom system, 


ed 


o, 


2. FUNCTIONAL DESCRIPTION OF CP/M, 


The user interacts with CP/M primarily through the CCP, which reads and 
interprets commands entered through the console, In general, the CCP 
addresses one of several disks which are online (the standard system addresses 
up to four different disk drives). These disk drives are labelled A, B, C, 
and D. A disk is “logged in” if the CCP is currently addressing the disk, In 
order to clearly indicate which disk is the currently logged disk, the CCP 
always prompts the operator with the disk name followed by the symbol ">" 
indicating that the CCP is ready for another command. Upon initial start up, 
the CP/M system is brought in from disk A, and the CCP displays the message 


xXK CP/M VER mm 


where xx 1S the memory size (in kilobytes) which this CP/M system manages, and 
m.m is the CP/M version number, All CP/M systems are initially set to operate 
in a 16K.memory space, but can be easily reconfigured to fit any memory size 
on the host system (see the MOVCPM transient canmand),. Following system 
Ssignon, CP/M automatically logs in disk A, prompts the user with the symbol 
"A>" (indicating that CP/M is currently addressing disk "A"), and waits for a 
command, The canmands are implemented at two levels: built-in commands and 
transient canmands, 


2.1. GENERAL COMMAND STRUCTURE, 
Built-in cammands are a part of the CCP program itself, while transient 


commands are loaded into the TPA from disk and executed, The built-in 
commands are 


ERA Erase specified files, 

DIR List file names in the directory. 

REN Rename the specified file, 

SAVE Save memory contents in a file, 

TYPE Type the contents of a file on the logged disk. 


Nearly all of the canmands reference a particular file or group of files, The 
form of a file reference is specified below. 


2.2. FILE REFERENCES, 


A file reference identifies a particular file or group of files on a 
particular disk attached to CP/M, These file references can be either 
"unambiguous" (ufn) or "“ambiguous" (afn). An unambiguous file reference 
uniquely identifies a single file, while an ambiguous file reference may be 














satisfied by a number of different files, 


File references consist of two parts: the primary name and the secondary 
name, Although the secondary name is optional, it usually is generic; that 
is, the secondary name "ASM," for example, is used to denote that the file is 
an assembly language source file, while the primary name distinguishes each 
particular source file, The two names are separated by a "." as shown below: 


PPPPPPPP. SSS 


where ppoppppp represents the primary name of eight characters or less, and 
sss is the secondary name of no more than three characters, As mentioned 
above, the name 


DPPPPPPP 


is also allowed and is equivalent to a secondary name consisting of three 
blanks, The characters used in specifying an wmnambiguous file reference 
cannot contain any of the special characters 

CP oe ES SPS 
while all alphanumerics and remaining special characters are allowed. 


An ambiguous file reference is used for directory search am pattern 
matching, The form of an ambiguous file reference is similar to an 
unambiguous reference, except the symbol "?" may be interspersed throughout 
the primary and secondary names, In various commands throughout CP/M, the "?" 
symbol matches any character of a file name in the "?" position, Thus, the 
ambiguous reference 


X?Z .C?M 
is satisfied by the unambiguous file names 
XYZ COM 
and 
X3Z .CAM 
Note that the ambiguous reference 
x x 
is equivalent to the ambiguous file reference 


while 


ed 
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Pppppppp.* 
and 
* sss 


are abbreviations for 


DPpppppp. ??? 
and 


respectively. As an example, 
DIR * x 


is interpreted by the CCP as a command to list the names of all disk files in 
the directory, while 


DIR X.Y 
searches only for a file by the name X.Y Similarly, the command 
DIR X?Y.CM 


causes a search for all (unambiguous) file names on the disk which satisfy 
this ambiguous reference, 


The following file names are valid unambiguous file references: 
X XYZ GAMMA 


X.Y XYZ ~COM GAMMA ,1 


As an added convenience, the programmer can generally specify the disk 
drive name along with the file name. In this case, the drive name is given as 
a letter A through Z followed by a colon (:). The specified drive is then 
“logged in” before the file operation occurs, Thus, the following are valid 
file nanes with disk name prefixes: 


A:X.Y B:XYZ C:GAMMA 
Z:XYZ COM B:X,A?M C:* ASM 
It should also be noted that all alphabetic lower case letters in file 


and drive names are always translated to upper case when they are processed by 
the CCP, 





3. SWITCHING DISKS, 


The operator can switch the currently logged disk by typing the disk 
drive name (A, B, C, or D) followed by a colon (:) when the CCP is waiting for 
console input. Thus, the sequence of prompts and commands shown below might 
occur after the CP/M system is loaded from disk A: 


16K CP/M VER 1.4 


A>DIR List all files on disk A, 

SAMPLE ASM 

SAMPLE PRN 

ADB: Switch to disk B. 

B>DIR *,ASM List all "ASM" files on B,. 

DUMP ASM 

FILES ASM 

B>A: Switch back to A, 
wy 
WwW 


4. THE FORM OF BUILT-IN COMMANDS. 


The file amd device reference forms deScribed above can now be used to 
fully specify the structure of the built-in canmands, In the description 
below, assume the following abbreviations: 


ufn = unambiguous file reference 
afn ambiguous file reference 
cr = carriage return 


Further, recall that the CCP always translates lower case characters to upper 
case characters internally. Thus, lower case alphabetics are treated as if 
they are upper case in canmand names and file references, 


4.1 ERA afn cr 


The ERA (erase) command removes files from the currently logged-in disk 
(1.e., the disk name currently prompted by CP/M preceding the ">"). The files 
which are erased are those which satisfy the ambiguous file reference afn, 
The following examples illustrate the use of ERA: 


ERA X,Y The file named X.Y on the currently logged disk 
is removed from the disk directory, and the space 
1s returned, 


ERA X,* All files with primary name X are removed from 
the current disk, 


ERA *,ASM All files with secondary name ASM are removed 
from the current disk, 


ERA X?Y.C?M All files on the current disk which satisfy the 
ambiguous reference X?Y.C?M are deleted, 


ERA *,* Erase all files on the current disk (in this case 
the CCP prompts the console with the message 
"ALL FILES (Y/N) ?" 
which requires a Y response before files are 
actually removed), 


ERA B:*,PRN All files on drive B which satisfy the ambiguous 
reference ????????.PRN are deleted, independently 
of the currently logged disk, 





4,2. DIR afn cr 
The DIR (directory) command causes the names of all files which satisfy 
the ambiguous file name afn to be listed at the console device. As a special 
case, the canmand 
DIR 


lists the files on the currently logged disk (the command "DIR" is equivalent 
to the canmand "DIR *,*"). Valid DIR commands are shown below. 


DIR X.Y 

DIR X?Z.C?M 

DIR ??.Y 

Similar to other CCP commands, the afn can be preceded by a drive name. 

The following DIR commands cause the selected drive to be addressed before the 
directory search takes place, 

DIR B: 

DIR B:X,Y 

DIR B:*,A?M 


If no files can be found on the selected diskette which satisfy the 
directory request, then the message “NOT FOUND” is typed at the console, 


4.3. REN ufnl=ufn2 cr 


The REN (rename) command allows the user to change the names of files on 
disk. The file satisfying ufn2 is changed to ufnl. The currently logged disk 
is assumed to contain the file to rename (ufnl). The CCP also allows the user 
to type a left-directed arrow instead of the equal sign, if the user’s console 
Supports this graphic character, Examples of the REN command are 


REN X, Y=Q.R The file Q.R is changed to X.Y. 
REN XYZ.COM=XYZ.XXX The file XYZ.XXX is changed to XYZ.COM, 


The operator can precede either ufnl or ufn2 (or both) by an optional 
drive address, Given that ufnl is preceded by a drive name, then ufn2 is 
assumed to exist on the same drive as ufnl. Similarly, if ufm2 is preceded by 
a drive nane, then ufnl is assumed to reside on that drive as well, If both 
ufnl and ufn2 are preceded by drive names, then the same drive must be 











specified in both cases, The following REN commands illustrate this format. 


REN A:X,ASM = Y.ASM The file Y.ASM is changed to X.ASM on 
drive A, 


REN B:ZAP,BAS=ZOT, BAS The file ZOT.BAS is changed to ZAP,BAS 
on drive B. 


REN B:A,ASM = B:A, BAK The file A.,BAK is renamed to A,ASM on 
drive B. 


If the file ufml is already present, the REN command will respond with 
the error "FILE EXISTS" and not perform the change, If ufm2 does not exist on 
the specified diskette, then the message "NOI FOUND" is printed at the 
console, 


4.4, SAVE n uf cr 


The SAVE command places n pages (256—byte blocks) onto disk from the TPA 
and names this file ufm, In the CP/M distribution system, the TPA starts at 
19@H (hexadecimal), which is the second page of memory. Thus, if the user's 
program occupies the area from 1@@H through 2FFH, the SAVE command must 
specify 2 pages of memory. The machine code file can be subsequently loaded 
and executed, Examples are: 


SAVE 3 X,.COM Copies 1@0@H through 3FFH to X.COM, 

SAVE 48 Q Copies 1@@H through 28FFH to Q (note 
that 28 is the page count in 28FFH, 
and that 28H = 2*16+8 = 4@ decimal). 

SAVE 4 X.Y Copies 10@H through 4FFH to X.Y. 


The SAVE command can also specify a disk drive in the afn portion of the 
command, as shown below. 


SAVE 18 B:ZOT.COM Copies 18 pages (190H through @AFFH) to 
the file ZOT.OCOM on drive B, 


4.5. TYPE ufn cr 


The TYPE command displays the contents of the ASCII source file ufn on 
the currently logged disk at the console device, Valid TYPE commands are 


TYPE X.Y 


TYPE X,PLM 
TYPE XXX 
The TYPE command expands tabs (clt-I characters), assumming tab positions 
are set at every eighth colum, The ufm can also reference a drive name as 
shown below, 


TYPE B:X.PRN The file X.PRN from drive B is displayed. 
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5. LINE EDITING AND OUTPUT OONTROL. 


The CCP allows certain line editing functions while typing command lines, 


rubout 


ctl-U 
ctl-x 


ctl-R 


ctl-E 


ctl=-C 


ctl=-Z 


Delete and echo the last character typed at the 
console, 


Delete the entire line typed at the console, 
(Same as ctl-U) 


Retype current canmand line: types a “clean line" fol- 
lowing character deletion with rubouts, 


Physical end of line: carriage is returned, but line 
is not sent wntil the carriage return key is depressed, 


CP/M system reboot (warm start) 


End input from the console (used in PIP and ED). 


The control functions ctl-P and ctl-S affect console output as shown below, 


ctl=P 


ctl-S 


Copy all subseguent console output to the currently 
asSigned list device (see the STAT command). Output 
is sent to both the list device and the console device 
until the next ctl-P is typed. 


Stop the console output temporarily. Program execution 
and output continue when the next character is typed 

at the console (e.g., another ctl-S). This feature is 
used to stop output on high speed consoles, such as 
CRIs, in order to view a segment of output before con- 
tinuing,. 


Note that the ctl-key sequences shown above are obtained by depressing the 
control and letter keys simultaneously. Further, CCP command lines can 
generally be up to 255 characters in lenath; they are not acted upon until the 
Carriage return key is typed. 


ll 


6. TRANSIENT COMMANDS, 


Transient commands are loaded from the currently logged disk and executed 
in the TPA. The transient commands defined for execution under the CCP are 
shown below, Additional functions can easily be defined by the user (see the 
LOAD command definition). 


STAT List the number of bytes of storage remaining on the 
currently logged disk, provide statistical information 
about particular files, and display or alter device 
assignment, 


ASM Load the CP/M assembler and assemble the specified 
program from disk, 


LOAD Load the file in Intel "hex" machine code format and 
produce a file in machine executable form which can be 
loaded into the TPA (this loaded program becomes a 
new command under the CCP), 


DDI Load the CP/M debugger into TPA and start execution, 

PIP Load the Peripheral Interchange Program for subsequent 
disk file and peripheral transfer operations, 

ED Load and execute the CP/M text editor program, 

SYSGEN Create a new CP/M system diskette, 

SUBMIT Submit a file of commands for batch processing. 

DUMP Dump the contents of a file in hex. 

MOVCPM Regenerate the CP/M system for a particular memory 
size, 


Transient commands are specified in the same manner as built-in commands, and 
additional commands can be easily defined by the user, As an added 
convenience, the transient command can be preceded by a drive name, which 
causes the transient to be loaded from the specified drive into the TPA for 
execution, Thus, the command 


B:STAT 
causes CP/M to temporarily “log in” drive B for the source of the STAT 


transient, and then return to the original logged disk for subsequent 
processing, 


LZ 


The basic transient commands are listed in detail below. 


6.1. STAT: cr 


The STAT command provides general statistical information about file 
storage and device assignment. It is initiated by typing one of the following 


forms: 


STAT cr 


STAT “command line" cr 


Special forms of the "command line" allow the current device assignment to be 
examined and altered as well. The variouS command lines which can be 
specified are shown below, with an explanation of each form shown to the 


right, 
STAT cr 
-- 
STAT x: cr 
STAT afn cr 
“on™ 


If the user types an empty command line, the STAT 
transient calculates the storage remaining on all 
active drives, and prints a message 


x: R/W, SPACE: nnnK 
or 
x: R/O, SPACE: nnnK 


for each active drive x, where R/W indicates the 
drive may be read or written, and R/O indicates 
the drive is read only (a drive becomes R/O by 
explicitly setting it to read only, as shown 
below, or by inadvertantly changing diskettes 
without performing a warm start). The space 
remaining on the diskette in drive x is given 

in kilobytes by nnn, 


If a drive name is given, then the drive is 
selected before the storage is computed. Thus, 
the command “STAT B:" could be issued while 
logged into drive A, resulting in the message 


BYTES REMAINING ON B: nnnkK 
The command line can also specify a set of files 
to be scanned by STAT, The files which satisfy 
afn are listed in alphabetical order, with stor- 
age requirements for each file under the heading 


RECS BYTS EX D: FILENAME,TYP 
rrrr bbbK ee d:pppppppp.sss 


where rrrr is the number of 128—byte records 
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allocated to the file, bbb is the number of kilo- 
bytes allocated to the file (bbb=rrrr*128/1024) , 
ee 1S the number of 16K extensions (ee=bbb/16) , 

d is the drive name containing the file (A...2), 
ppoppppp is the (up to) eight-—character primary 
file name, and sss is the (up to) three-character 
secondary name. After listing the individual 
files, the storage usage is summarized, 


STAT x:afn cr As a convenience, the drive name can be given 
ahead of the atn, In this case, the specified 
drive is first selected, and the form "STAT afn" 
1S executed, 


STAT x:=R/O cr This form sets the drive given by x to read-only, 
which remains in effect until the next warm or 
cold start takes place, When a disk is read-only, 
the message 


BDOS ERR ON x: READ ONLY 


will appear if there is an attempt to write to 
the read-only disk x. CP/M waits until a key 
is depressed before performing an automatic warm 
start (at which time the disk becomes R/W). 


The STAT command also allows control over the physical to logical device 
asSignment (see the IOBYTE function described in the manuals "CP/M Interface 
Guide” and "CP/M System Alteration Guide"), In general, there are four 
logical peripheral devices which are, at any particular instant, each assigned 
to one of several physical peripheral devices. The four logical devices are 
named: 


CON: The system console device (used by CCP 
for communication with the operator) 

RDR: The paper tape reader device 

PUN: The paper tape punch device 

LST: The output list device 


The actual devices attached to any particular computer system are driven 
by subroutines in the BIOS portion of CP/M, Thus, the logical RDR: device, 
for example, could actually be a high speed reader, Teletype reader, or 
cassette tape. In order to allow some flexibility in device naming and 
assignment, several physical devices are defined, as shown below: 
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TTY: Teletype device (Slow speed console) 


CRT: Cathode ray tube device (high speed console) 

BAT: Batch processing (console is current RDR:, 
output goes to current LST: device) 

UC1: User-defined console 

PTR: Paper tape reader (high speed reader) 

URI: User-defined reader #1 

UR2: User-defined reader #2 

PIP: Paper tape punch (high speed punch) 

UP1: User-defined punch #1 

UP2: User-defined punch #2 

LPT: Line printer 

ULL: User-defined list device #1 


It must be emphasized that the physical device names may or may not 
actually correspond to devices which the names imply. That is, the PIP: 
device may be implemented as a cassette write operation, if the user wishes, 
The exact correspondence and driving subroutine is defined in the BIOS portion 
of CP/M, In the standard distribution version of CP/M, these devices 
correspond to their names on the MDS 800 development system. 


The possible logical to physical device assignments can be displayed by 


typing 
STAT VAL: cr 


The STAT prints the possible values which can be taken on for each logical 
device: 


CON. = TTY: CRI: BAT: UCI: 
RDR: = TTY: PIR: URI: UR2: 
PUN: = TTY: PYTP: UPl: UP2: 
LST: = TTY: CRI: LP: ULL: 


In each case, the logical device shown to the left can take any of the four 
physical assignments shown to the right on each line, The current logical to 
physical mapping is displayed by typing the command 


STAT DEV: cr 
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which produces a listing of each logical device to the left, and the current 
corresponding physical device to the right, For example, the list might 
appear as follows: 


CON: = CRT: 
RDR: = URI: 
PUN: = PIP: 
LST: = TTY: 


The current logical to physical device assignment can be changed by typing a 
STAT command of the form 


STAT 1dl = pdl, 1d2 = pd2 , ... , ldn = pdncr 
where ldl through ldn are logical device names, and pdl through fpdn are 
compatible physical device names (i.e., ldi and pdi appear on the same line in 
the "VAL:" cammand shown above). The following are valid STATI’ commands which 
change the current logical to physical device assignments: 


STAT QON:=CRT: cr 
STAT PUN: = TTY:,LST:=LPT:, ROR:=TTY: cr 


6.2. ASM ufM cr 
The ASM command loads and executes the CP/M 8080 assembler. The ufn 
specifies a source file containing assembly language statements where the 
secondary name is assumed to be ASM, and thus is not specified. The following 
ASM commands are valid: 
ASM X 
ASM GAMMA 


The two-pass assembler is automatically executed. If assembly errors occur 
during the second pass, the errors are printed at the console, 


The assembler produces a file 
xX. PRN 
where x is the primary name specified in the ASM command. The PRN file 
contains a listing of the source program (with imbedded tab characters if 


present in the source program), along with the machine code generated for each 
statement and diagnostic error messages, if any. The PRN file can be listed 
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at the console using the TYPE command, or sent to a peripheral device using 
PIP (see the PIP command structure below). Note also that the PRN file 
contains the original source program, augmented by miscellaneous assembly 
information in the leftmost 16 colums (program addresses and hexadecimal 
machine code, for example). Thus, the PRN file can serve as a backup for the 
Original source file: if the source file is accidently removed or destroyed, 
the PRN file can be edited (see the ED operator's guide) by removing the 
leftmost 16 characters of each line (this can be done by issuing a single 
editor “macro” canmand). The resulting file is identical to the original 
source file and can be renamed (REN) from PRN to ASM for subsequent editing 
and assembly. The file 


xX, HEX 


is also produced which contains 8988 machine language in Intel “hex” format 
Suitable for subseguent loading and execution (see the LOAD command). For 
complete details of CP/M’s assembly language program, see the "CP/M Assembler 
Language (ASM) User’s Guide," 


Similar to other transient commands, the source file for assembly can be 
taken fram an a.ternate disk by prefixing the assembly language file name by a 
disk drive name. Thus, the canmand 

ASM B:ALPHA cr 
loads the assembler from the currently logged drive and operates upon the 


source program ALPHA.ASM on drive B. The HEX and PRN files are also placed on 
drive B in this case, 


6.3. LOAD uf cr 
The LOAD command reads the file ufn, which is assumed to contain "hex" 
format machine code, and produces a memory image file which can be 
Subsequently executed, The file name ufn is assumed to be of the form 
X HEX 


and thus only the name x need be specified in the command. The LOAD command 
creates a file named 


X .COM 
which marks it as containing machine executable code. The file is actually 
loaded into memory and executed when the user types the file name x 
immediately after the prompting character “>" printed by the CCP, 
In general, the CCP reads the name x following the prompting character 


and looks for a built-in function name. If no function name is found, the CCP 
Searches the system disk directory for a file by the name 
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X COM 


If found, the machine code is loaded into the TPA, and the program executes, 
Thus, the user need only LOAD a hex file once; it can be subsequently 
executed any number of times by simply typing the primary name. In this way, 
the user can “invent" new commands in the CCP, (Initialized disks contain the 
transient canmands as (COM files, which can be deleted at the user’s option.) 
The operation can take place on an alternate drive if the file name is 
prefixed by a drive name. Thus, 


LOAD B:BETA 


brings the LOAD program into the TPA from the currently logged disk and 
operates upon drive B after execution begins, 


It must be noted that the BETA.HEX file must contain valid Intel format 
hexadecimal machine code records (as produced by the ASM program, for example) 
which begin at 190H, the beginning of the TPA. Further, the addresses in the 
hex records must be in ascending order; gaps in wnfilled memory regions are 
filled with zeroes by the LOAD command as the hex records are read, Thus, 
LOAD must be used only for creating CP/M standard "COM" files which operate in 
the TPA, Programs which occupy regions of memory other than the TPA can be 
loaded under DDI. 


6.4, PIP cr 


PIP is the CP/M Peripheral Interchange Program which implements the basic 
media conversion operations necessary to load, print, punch, copy, and combine 
disk files, The PIP program is initiated by typing one of the following forms 


(1) PIP cr 
(2) PIP “command line” cr 


In both cases, PIP is loaded into the TPA and executed, In case (1), PIP 
reads command lines directly from the console, prompted with the "*" 
character, until an empty command line is typed (i.e., a single carriage 
return is issued by the operator). Each successive command line causes some 
media conversion to take place according to the rules shown below, Form (2) 
of the PIP command is equivalent to the first, except that the single command 
line given with the PIP command is automatically executed, and PIP terminates 
immediately with no further prompting of the console for input command lines, 
The form of each cammand line is 


destination = source#l, source#2, ... , source#n cr 


where "destination" is the file or peripheral device to receive the data, and 
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"“source#l, ..., Sourcefn” represents a series of one or more files or devices 
which are copied from left to right to the destination, 


When multiple files are given in the command line (i.e, n> 1), the 
individual files are assumed to contain ASCII characters, with an assumed CP/M 
end-of-file character (ctl-Z) at the end of each file (see the O parameter to 
override this assumption). The equal symbol (=) can be replaced by a 
left-oriented arrow, if your console supports this ASCII character, to improve 
readability. Lower case ASCII alphabetics are internally translated to upper 
case to be consistent with CP/M file and device name conventions, Finally, 
the total command line length cannot exceed 255 characters (ctl-E can be used 
to force a phySical carriage return for lines which exceed the console width). 


The destination and source elements can be unambiguous references to CP/M 
source files, with or without a preceding disk drive name, That is, any file 
can be referenced with a preceding drive name (A:, B:, C:, or D:) which 
defines the particular drive where the file may be obtained or stored, When 
the drive name is not included, the currently logged disk is assumed, 
Further, the destination file can also appear as one or more of the source 
files, in which case the source file is not altered until the entire 
concatenation is complete, If the destination file already exists, it is 
removed if the command line is properly formed (it is not removed if an error 
condition arises). The following command lines (with explanations to the 
right) are valid as input to PIP: 


X =Yocr Copy to file X from file Y, 
where X and Y are unambiguous 
file names; Y remains unchanged, 


X =Y,Z cr Concatenate files Y and Z and 
copy to file X, with Y and Z 
unchanged, 

X ,AASM=Y.ASM,Z.ASM,FIN.ASM cr Create the file X.ASM from the 
concatenation of the Y, Z, and 
FIN files with type ASM, 

NEW.ZOT = B:OLD.ZAP cr Move a copy of OLD.ZAP from drive 
B to the currently logged disk; 
name the file NEW.ZOT,. 

B:A.U = B:B.V,A:C.W,D.X cr Concatenate file B.V from drive B 


with C.W from drive A and D,X. 
from the logged disk: create 
the file A.U on drive B, 


For more convenient use, PIP allows abbreviated commands for transferring 
files between disk drives, The abbreviated forms are 
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PIP x:=afn cr 
PIP x:=y:afn cr 
PIP ufn = ys: cr 
PIP x:ufM = - cr 


The first form copies all files from the currently logged disk which satisfy 
the afm to the same file names on drive x (x = A,...Z). The second form is 
eguivalent to the first, where the source for the copy is drive y (y = A... 
Z). The third form is eguivalent to the command "PIP ufn=y:ufn cr" which 
copies the file given by ufn from drive y to the file ufn on drive x. The 
fourth form is equivalent to the third, where the source disk is explicitly 
given by y. 


Note that the source and destination disks must be different in all of 
these cases, If an afn is specified, PIP lists each ufn which satisfies the 
afn as it is being copied. If a file exists by the same name as the 
destination file, it is removed upon successful completion of the copy, and 
replaced by the copied file, 


The following PIP commands give examples of valid disk-to-disk copy 
operations: 


~~ 
B:=*,QOM cr Copy all files which have the 
secondary name "COM" to drive B 
from the current drive, 
A:=B:ZAP.* cr Copy all files which have the 
primary name "ZAP" to drive A 
from drive B. 
ZAP.ASM=B: cr Equivalent to ZAP,ASM=B:ZAP.ASM 
B:ZOT.COM=A: cr Eauivalent to B:ZOT,COM=A:ZOT,COM 
B:=GAMMA,.BAS cr Same as B:GAMMA, BAS=GAMMA, BAS 
B:=A:GAMMA,BAS cr Same as B:GAMMA, BAS=A:GAMMA,BAS 
PIP also allows reference to physical and logical devices which are 
attached to the CP/M system. The device names are the same aS given under the 
STAT command, along with a number of specially named devices, The logical 
devices given in the STAT command are 
CON: (console), RDR: (reader), PUN: (punch), and LST: (1ist) 
while the physical devices are 
WwW 
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TTY: (console, reader, punch, or 11st) 

CRI: (console, or list), UCl: (console) 
PTR: (reader), UR]: (reader), UR2: (reader) 
PTP: (punch), UPl: (punch), UbP2: (punch) 
LPr: (list), ULl: (list) 


(Note that the "BAT:" physical device is not included, since this assignment 
is used only to indicate that the RDR: and LST: devices are to be used for 


console input/output.) 


The RDR, LST, PUN, and COON devices are all defined within the BIOS 
portion of CP/M, and thus are easily altered for any particular I/O system. 
(The current physical device mapping is defined by JIOBYTE; see the "CP/M 
Interface Guide" for a discussion of this function), The destination device 
must be capable of receiving data (i.e., data cannot be sent to the punch), 
and the source devices must be capable of generating data (i.e., the LST: 
device cannot be read). 


The additional device names which can be used in PIP commands are 


NUL: Send 48 “nulls" (ASCII @°s) to the device 
(this can be issued at the end of punched output), 


EOF : Send a CP/M end-of-file (ASCII ctl-Z) to the 
destination device (sent automatically at the 
end of all ASCII data transfers through PIP). 


INP: Special PIP input source which can be "patched" 
into the PIP program itself: PIP gets the input 
data character-by-character by CALLing location 
193H, with data returned in location 109H (parity 
bit must be zero), 


OUT: Special PIP output destination which can be 
patched into the PIP program: PIP CALLs location 
196H with data in register C for each character 
to transmit, Note that locations 109H through 
1FFH of the PIP memory image are not used and 
can be replaced by special purpose drivers using 
DDI (see the DDI operator’s manual). 


PRN: Same as LST:, except that tabs are expanded at 
every eighth character position, lines are 
numbered, and page ejects are inserted every 60 
lines, with an initial eject (same as [t8np]). 


File and device names can be interspersed in the PIP commands. In each 
case, the specific device is read wntil end-of-file (ctl-Z for ASCII files, 
and a real end of file for non-ASCII disk files), Data from each device or 
file is concatenated from left to right until the last data source has been 
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read, The destination device or file is written using the data from the 
source files, and an end-of-file character (ctl-Z) is appended to the result 
for ASCII files, Note if the destination is a disk file, then a temporary 
file is created ($$$ secondary name) which is changed to the actual file name 
only upon successful campletion of the copy. Files with the extension "COM" 
are always assumed to be non-ASCII. 


The copy operation can be aborted at any time by depressing any key on 
the keyboard (a rubout suffices). PIP will respond with the message "ABORTED" 
to indicate that the operation was not campleted. Note that if any operation 
is aborted, or if an error occurs during processing, PIP removes any pending 
commands which were set up while uSing the SUBMIT command. 


It should also be noted that PIP performs a special function if the 
destination is a disk file with type "HEX" (an Intel hex formatted machine 
code file), and the source is an external peripheral device, such as a paper 
tape reader. In this case, the PIP program checks to ensure that the source 
file contains a properly formed hex file, with legal hexadecimal values and 
checksum records, When an invalid input record is found, PIP reports an error 
message at the console and waits for corrective action, It is usually 
sufficient to open the reader and rerun a section of the tape (pull the tape 
back about 20 inches). When the tape is ready for the re-read, type a single 
Carriage return at the console, and PIP will attempt another read. If the 
tape position cannot be properly read, simply continue the read (by typing a 
return following the error message), and enter the record manually with the ED 
program after the disk file is constructed. For convenience, PIP allows the 
end-of-file to be entered from the console if the source file is a ROR: 
device. In this case, the PIP program reads the device and monitors the 
keyboard. If ctl-Z is typed at the keyboard, then the read operation is 
terminated normally. 


Valid PIP commands are shown below, 


PIP LST: = X,PRN cr Copy X.PRN to the LST device and 
terminate the PIP program. 


PIP cr Start PIP for a sequence of 
commands (PIP prompts with "*"), 


*QON:=X.ASM,Y.ASM,Z.ASM cr Concatenate three ASM files and 
copy to the CON device, 


*XHEX=CON: , Y.HEX,PTR: cr Create a HEX file by reading the 
CON (until a ctl-Z is typed), fol- 
lowed by data from Y.HEX, followed 
by data from PTR until a ctl-Z is 
encountered, 


*cr Single carriage return stops PIP, 
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PIP PUN:=NUL: ,X.ASM,EOF:,NUL: cr Send 48 nulls to the punch device; 
then copy the X.ASM file to the 
punch, followed by an end-of—file 
(ctl-Z) and 40 more null charac- 
ters, 


The user can also specify one or more PIP parameters, enclosed in left 
and right square brackets, separated by zero or more blanks, Each parameter 
affects the copy operation, and the enclosed list of parameters must 
immediately follow the affected file or device, Generally, each parameter can 
be followed by an optional decimal integer value (the S and 0 parameters are 
exceptions). The valid PIP parameters are listed below. 


B Block mode transfer: data is buffered by PIP until an ASCII 
x-off character (ctl-S) is received from the source device, 
This allows transfer of data to a disk file from a continuous 
reading device, such as a cassette reader. Upon receipt of 
the x-off, PIP clears the disk buffers and returns for more 
input data. The amount of data which can be buffered is de- 
pendent upon the memory size of the host system (PIP will 
issue an error message if the buffers overflow). 


Dn Delete characters which extend past column n in the transfer 
of data to the destination from the character source, This 
parameter is used most often to truncate long lines which are 
sent to a (narrow) printer or console device, 


E Echo all transfer operations to the console as they are being 
performed, 
F Filter form feeds from the file, All imbedded form feeds are 


removed. The P parameter can be used simultaneously to 
insert new form feeds, 


H Hex data transfer: all data is checked for proper Intel hex 
file format. Non-essential characters between hex records 
are removed during the copy operation, The console will be 
prompted for corrective action in case errors occur, 


I Ignore ":@@" records in the transfer of Intel hex format 
file (the I parameter automatically sets the H parameter). 


L Translate upper case alphabetics to lower case, 


N Add line numbers to each line transferred to the destination 
starting at one, and incrementing by 1. Leading zeroes are 
suppressed, and the number is followed by a colon, If N2 
is specified, then leading zeroes are included, and a tab is 
inserted following the number. The tab is expanded if T is 
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set, 


O Object file (non-ASCII) transfer: the normal CP/M end of 
file is iqnored, 


Pn Include page ejects at every n lines (with an initial page 
eject). If n= 1 or is excluded altogether, page ejects 
occur every 6@ lines, If the F parameter is used, form feed 
suppression takes place before the new page ejects are 
inserted. 


Qstz Quit copying from the source device or file when the 
string s (terminated by ctl-Z) is encountered, 


Sstz Start copying from the source device when the string s is 
encountered (terminated by ctl-Z). The S and Q parameters 
can be used to “abstract” a particular section of a file 
(such aS a subroutine). The start and quit strings are al- 
ways included in the copy operation, 


NOTE -— the strings following the s and g parameters are 

translated to upper case by the CCP if form (2) of the 

PIP command is used. Form (1) of the PIP invocation, how- 

ever, does not perform the automatic upper case translation, a, 
(1) PIP cr 
(2) PIP "command line” cr 


Tn Expand tabs (ctl-I characters) to every nth column during the 
transfer of characters to the destination from the source, 


U Translate lower case alphabetics to upper case during the 
the copy operation, 


V Verify that data has been copied correctly by rereading 
after the write operation (the destination must be a disk 
file). 


Z zero the parity bit on input for each ASCII character, 


The following are valid PIP commands which specify parameters in the file 
transfer: 


PIP X,ASM=B:[v] cr Copy X.ASM from drive B to the current drive 
and verify that the data was properly copied. 


PIP LPT:=X,ASM([(nt8u] cr Copy X.ASM to the LPT: devices number each 
line, expand tabs to every eighth colum, and 
translate lower case alphabetics to upper 
case, 
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PIP PUN:=X,.HEX[1i] ,Y.ZOT[h] cr First copy. X.HEX to the PUN: device and 
ignore the trailing ":@0" record in X,HEX; 
then continue the transfer of data by reading 
Y.ZOT, which contains hex records, including 
any ":@0" records which it contains, 


PIP X,LIB = Y.ASM [ sSSUBR1:'z qQJMP L3?z ] cr Copy from the file Y.ASM 
into the file X.LIB. Start the copy when the 
string "SUBR1:" has been found, and quit copy- 
ing after the string "JMP L3" is encountered. 


PIP PRN:=X.ASM [p59] Send X,ASM to the LST: device, with line num 
bers, tabs expanded to every eighth column, 
and page ejects at every 5@th line. Note that 
nt8p608 is the assumed parameter list for a PRN 
file: p5@ overrides the default value. 


6.5. ED ufn cr 


The ED program is the CP/M system context editor, which allows creation 
and alteration of ASCII files in the CP/M environment. Complete details of 
operation are given the ED user’s manual, "ED: a Context Editor for the CP/M 
Disk System." In general, ED allows the operator to create and operate upon 
source files which are organized as a sequence of ASCII characters, separated 
by end-of-line characters (a carriage-return line-feed seguence). There is no 
practical restriction on line length (no single line can exceed the size of 
the working memory), which is instead defined by the number of characters 
typed between cr’s, The ED program has a number of commands for character 
string searching, replacement, and insertion, which are useful in the creation 
and correction of programs or text files under CP/M. Although the CP/M has a 
limited memory work space area (approximately 5800 characters in a 16K CP/M 
system), the file size which can be edited is not limited, since data is 
easily “paged” through this work area, 


Upon initiation, ED creates the specified source file, if it does not 
exist, and opens the file for access, The programmer then "appends" data from 
the source file into the work area, if the source file already exists (see the 
A command), for editing, The appended data can then be displayed, altered, 
and written from the work area back to the disk (see the W command). 
Particular points in the program can be automatically paged and located by 
context (see the N command), allowing easy access to particular portions of a 
large file, 


Given that the operator has typed 


ED X,ASM cr 
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the ED program creates an intermediate work file with the name 


X.$S$ 


to hold the edited data during the ED run, Upon completion of ED, the X,ASM 
file (original file) is renamed to X.BAK, and the edited work file is renamed 
to X.ASM. Thus, the X,BAK file contains the original (unedited) file, and the 
X.ASM file contains the newly edited file, The operator can always return to 
the previous version of a file by removing the most recent version, and 
renaming the previous version, Suppose, for example, that the current X.ASM 
file was improperly edited; the sequence of CCP command shown below would 
reclaim the backup file, 


DIR X,* Check to see that BAK file 
1S available, 

ERA X,ASM Erase most recent version, 

REN X,ASM=X, BAK Rename the BAK file to ASM, 


Note that the operator can abort the edit at any point (reboot, power failure, 
ctl-C, or Q command) without destroying the original file, In this case, the 
BAK file is not created, and the original file is always intact. 


The ED program also allows the user to “ping=-pong" the source and create 
backup files between two disks. The form of the ED command in this case is 


ED ufn d: 


where ufnm is the name of a file to edit on the currently logged disk, and d is 
the name of an alternate drive, The ED program reads and processes the source 
file, and writes the new file to drive d, using the name ufn, Upon completion 
of processing, the original file becomes the backup file, Thus, if the 
operator is addressing disk A, the following command is valid: 


ED X,ASM B: 


which edits the file X.ASM on drive A, creating the new file xX.SSS on drive 
B. Upon canpletion of a successful edit, A:X.ASM is renamed to A:X.BAK, and 
B:X.$$$ is renamed to B:X.ASM, For user convenience, the currently logged 
disk becomes drive B at the end of the edit. Note that if a file by the name 
B:X.ASM exists before the editing begins, the message 


FILE EXISTS 
is printed at the console as a precaution against accidently destroying a 


source file, In this case, the operator must first ERAse the existing file 
and then restart the edit operation, 
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Similar to other transient canmands, editing can take place on a drive 
different from the currently logged disk by preceding the source file name by 
a drive name, Examples of valid edit requests are shown below 


ED A:X.ASM Edit the file X.ASM on drive A, with 
new file and backup on drive A, 





ED B:X.ASM A: Edit the file X.ASM on drive B to the | 
temporary file X.$$$ on drive A, On | 
termination of editing, change X,ASM 
on drive B to X.BAK, and change x.S$$$ 
on drive A to X,ASM, 


6.6. SYSGEN cr 


The SYSGEN transient canmand allows generation of an initialized diskette 
containing the CP/M operating system. The SYSGEN program prompts the console 
for canmands, with interaction as shown below. 


SYSGEN cr Initiate the SYSGEN program. 
SYSGEN VERSION m.m SYSGEN Sign-on message, 


SOURCE DRIVE NAME (OR RETURN TO SKIP) 
Respond with the drive name (one 
of the letters A, B, C, or D) of 
the disk containing a CP/M sys- 
tem; usually A. If a copy of 
CP/M already exists in memory, 
due to a MOVCPM command, type a 
cr only. Typing a drive name 
x will cause the response: | 


SOURCE ON x THEN TYPE RETURN Place a diskette containing the 
CP/M operating system on drive 
x (x 1S one of A, B, C, or D). 
Answer with cr when ready. 





FUNCTION COMPLETE System is copied to memory. 
SYSGEN will then prompt with: 


DESTINATION DRIVE NAME (OR RETURN TO REBOOT) 

If a diskette is being ini- 
tialized, place the new disk 
into a drive and answer with 
the drive name, Otherwise, type 
a cr and the system will reboot 
from drive A, Typing drive name 
xX will cause SYSGEN to prompt 
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with: 


DESTINATION ON x THEN TYPE RETURN Place new diskette into drive 
Xx; type return when ready. 


FUNCTION COMPLETE New diskette is initialized 
in drive x, 


The "DESTINATION" prompt will be repeated until a single carriage return is 
typed at the console, so that more than one disk can be initialized. 


Upon canpletion of a successful system generation, the new diskette 
contains the operating system, and only the built-in commands are available, 
A factory-fresh IBM-compatible diskette appears to CP/M as a diskette with an 
empty directory; therefore, the operator must copy the appropriate OOM files 
from an existing CP/M diskette to the newly constructed diskette using the PIP 
transient. 


The user can copy all files from an existing diskette by typing the PIP 
command 


PIP B: = A: *,¥*[v] cr 


which copies all files from disk drive A to disk drive B, and verifies that 
each file has been copied correctly. The name of each file is displayed at 
the console as the copy operation proceeds, 


It should be noted that a SYSGEN does not destroy the files which already 
exist on a diskette; it results only in construction of a new operating 
system. Further, if a diskette is being used only on drives B through D, and 
will never be the source of a bootstrap operation on drive A, the SYSGEN need 
not take place. In fact, a new diskette needs absolutely no initialization to 
be used with CP/M, 


6.7. SUBMIT ufn parm#] ... parm#n cr 


The SUBMIT command allows CP/M commands to be batched together for 
automatic processing, The ufn given in the SUBMIT command must be the 
filename of a file which exists on the currently logged disk, with an assumed 
file type of "SUB.“ The SUB file contains CP/M prototype commands, with 
possible parameter substitution, The actual parameters parm#l ... parm#n are 
substituted into the prototype commands, and, if no errors occur, the file of 
substituted canmands are processed seguentially by CP/M. 
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The prototype command file is created using the ED program, with 
interspersed "S$" parameters of the form 


SLY °S2) 33° wae -3n 


corresponding to the number of actual parameters which will be included when 
the file is submitted for execution, When the SUBMIT transient is executed, 
the actual parameters parm#]1 ... parm#n are paired with the formal parameters 
Sl ... $n in the prototype cammands, If the number of formal and actual 
parameters does not correspond, then the submit function is aborted with an 
error message at the console. The SUBMIT function creates a file of 
Substituted canmands with the name 


$$$ .SUB 


on the logged disk. When the system reboots (at the termination of the 
SUBMIT), this canmand file is read by the CCP as a source of input, rather 
than the console. If the SUBMIT function is verformed on any disk other than 
drive A, the commands are not processed until the disk is inserted into drive 
A and the system reboots. Further, the user can abort command processing at 
any time by typing a rubout when the command is read and echoed. In this 
case, the $$S.SUB file is removed, and the subsequent commands come from the 
console. Command processing is also aborted if the CCP detects an error in 
any of the canmands, Programs which execute under CP/M can abort processing of 
command files when error conditions occur by simply erasing any existing 
S$$.SUB file, 


In order to introduce dollar signs into a SUBMIT file, the user may type 
a "SS" which reduces to a single "S$" within the command file, Further, an 
up-arrow symbol "*" may precede an alphabetic character x, which voroduces a 
Single ctl-x character within the file, 


The last canmand in a SUB file can initiate another SUB file, thus 
allowing chained batch commands, 


Suppose the file ASMBL.SUB exists on disk and contains the prototype 
commands 
ASM $l 
DIR $1.* 
ERA *, BAK 
PIP $2:=$1.PRN 
ERA $1.PRN 


and the canmand 
SUBMIT ASMBL X PRN cr 


is issued by the operator, The SUBMIT program reads the ASMBL.SUB file, 
substituting "X" for all occurrences of $l and "PRN" for all occurrences of 
$2, resulting in a $$$,SUB file containing the commands 





which are executed in sequence by the CCP, 


The SUBMIT function can access a SUB file which is on an alternate drive 
by preceding the file name by a drive name, Submitted files are only acted 
upon, however, when they appear on drive A. Thus, it is possible to create a 
Submitted file on drive B which is executed at a later time when it is 
inserted in drive A, 


6.8, DUMP ufM cr 


The DUMP program types the contents of the disk file (ufn) at the console 
in hexadecimal form. The file contents are listed sixteen bytes at a time, 
with the absolute byte address listed to the left of each line in 
hexadecimal. Long typeouts can be aborted by pushing the rubout key during 
printout. (The source listing of the DUMP program is given in the "CP/M 
Interface Guide” as an example of a program written for the CP/M environment.) 


6.9. MOVCPM cr 


The MOVCPM program allows the user to reconfigure the CP/M system for any 
particular memory size. Two optional parameters may be used to indicate (1) 
the desired size of the new system and (2) the disposition of the new system 
at program termination. If the first parameter is amitted or a "*" is given, 
the MOVCPM program will reconfigure the system to itS maximum size, based upon 
the kilobytes of contiguous RAM in the host system (starting aat @@00H). If 
the second parameter is omitted, the system is executed, but not permanently 
recorded; if "*" is given, the system is left in memory, ready for a SYSGEN 
operation, The MOVCPM program relocates a memory image of CP/M and places 
this image in memory in preparation for a system generation operation, The 
command forms are: 


MOVCPM cr Relocate and execute CP/M for manage—- 
ment of the current memory configura- 
tion (memory is examined for contigu- 
ous RAM, starting at 100H). Upon com 
pletion of the relocation, the new 
system is executed but not permanently 
recorded on the diskette, The system 
which is constructed contains a BIOS 
for the Intel MDS 880. 
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MOVCPM n cr Create a relocated CP/M system for 
management of an n kilobyte system (n 
must be in the range 16 to 64), and 
execute the system, aS described above. 


MOVCPM * * cr Construct a relocated memory image for 
the current memory configuration, but 
leave the memory image in memory, in 
preparation for a SYSGEN operation, 


MOVCPM n * cr Construct a relocated memory image for 
an n kilobyte memory system, and leave 
the memory image in preparation for a 
SYSGEN operation, 


The canmand 
MOVCPM * * 


for example, constructs a new version of the CP/M system and leaves it in 
memory, ready for a SYSGEN operation, The message 


READY FOR "SYSGEN" OR 
“SAVE 32 CPMxx,COM" 


is printed at the console upon completion, where xx is the current memory size 
in kilobytes, The operator can then type 


SYSGEN cr Start the system generation, 


SOURCE DRIVE NAME (OR RETURN TO SKIP) Respond with a cr to skip 
the CP/M read operation since the system 
1s already in memory as a result of the 
previous MOVCPM operation, 


DESTINATION DRIVE NAME (OR RETURN T@ REBOOT) 
Respond with B to write new system 
to the diskette in drive B. SYSGEN 
will prompt with: 

DESTINATION ON B, THEN TYPE RETURN 


Ready the fresh diskette on drive 
B and type a return when ready. 


Note that if you respond with "A" rather than "B" above, the system will be 
written to drive A rather than B. SYSGEN will continue to type the prompt: 


DESTINATION DRIVE NAME (OR RETURN TO REBOOT) — 


until the operator responds with a single carriage return, which stops the 


31 





SYSGEN program with a system reboot, 


The user can then go through the reboot process with the old or new 
diskette, Instead of performing the SYSGEN operation, the user could have 


typed 
SAVE 32 CPMxx,COM 


at the canpletion of the MOVCPM function, which would place the CP/M memory 
image on the currently logged disk in a form which can be “patched.” This is 
necessary when operating in a non-standard environment where the BIOS must be 
altered for a particular peripheral device configuration, as described in 
the"CP/M System Alteration Guide," 


Valid MOVCPM commands are given below: 


MOVCPM 48 cr Construct a 48K verskon of CP/M and start 
execution, 
MOVCPM 48 * cr Construct a 48K version of CP/M in prepara- 


tion for permanent recording; response is 


READY FOR "SYSGEN" OR 
“SAVE 32CPM48,COM" 


MOVCPM * * cr Construct a maximum memory version of CP/M 
and start execution, 


It is important to note that the newly created system is serialized with 
the number attached to the original diskette and is subject to the conditions 
of the Digital Research Software Licensing Agreement, 
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7.  BDOS ERROR MESSAGES, 


There are three error situations which the Basic Disk Operating System 
intercepts during file processsing. When one of these conditions is detected, 
the BDOS prints the message: 


BDOS ERR ON xs: error 
where x is the drive name, and “error” is one of the three error messages: 


BAD SECTOR 
SELECT 
READ ONLY 


The "BAD SECTOR" message indicates that the disk controller electronics 
has detected an error condition in reading or writing the diskette, This 
condition is generally due to a malfunctioning disk controller, or an 
extremely worn diskette, If you find that your system reports this error more 
than once a month, you should check the state of your controller electronics, 
and the condition of your media. You may also encounter this condition in 
reading files generated by a controller produced by a different manufacturer, 
Even though controllers are claimed to be IBM-compatible, one often finds 
small differences in recording formats, The MDS-800 controller, for example, 
requires two bytes of one’s following the data CRC byte, which is not required 
in the IBM format. As a result, diskettes generated by the Intel MDS can be 
read by almost all other IBM-compatible systems, while disk files generated on 
other manufacturer’s equipment will produce the "BAD SECTOR" message when read 
by the MDS, In any case, recovery from this condition is accomplished by 
typing a ctl-C to reboot (this is the safest!), or a return, which simply 
ignores the bad sector in the file operation, Note, however, that typing a 
return may destroy your diskette integrity if the operation is a directory 
write, so make sure you have adeauate backups in this case, 


The "SELECT“” error occurs when there iS an attempt to address a drive 
beyond the A through D range. In this case, the value of x in the error 
message gives the selected drive. The system reboots following any input from 
the console, 


The "READ ONLY" mesSage occurs when there is an attempt to write to a 
diskette which has been designated as read-only in a STAT command, or has been 
set to read-only by the BDOS, In general, the operator should reboot CP/M 
either by using the warm start procedure (ctl-C) or by performing a cold start 
whenever the diskettes are changed. If a changed diskette is to be read but 
not written, BDOS allows the diskette to be changed without the warm or cold 
start, but internally marks the drive as read-only. The status of the drive 
is subsequently changed to read/write 1f a warm or cold start occurs. Upon 
issuing this message, CP/M waits for input from the console, An automatic 
warm start takes place following any input. 
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8, OPERATION OF CP/M ON THE MDS, 


This section gives operating procedures for using CP/M on the Intel MDS 
microcomputer development system, A basic knowledge of the MDS hardware and 
software systems 1S assumed, 


CP/M is initiated in essentially the same manner as Intel’s ISIS 
operating system, The disk drives are labelled @ through 3 on the MBS, 
corresponding to CP/M drives A through D, respectively. The CP/M system 
diskette is inserted into drive 8, and the BOOT and RESET switches are 
depressed in sequence, The interrupt 2 light should go on at this point, The 
Space bar is then depressed on the device which is to be taken as the system 
console, and the light should go out (if it does not, then check connections 
and baud rates). The BOOT switch is then turned off, and the CP/M signon 
message should appear at the selected console device, followed by the "A>" 
system prompt. The user can then issue the various resident and transient 
commands 


The CP/M system can be restarted (warm start) at any time by pushing the 
INT @ switch on the front panel, The built-in Intel ROM monitor can be 
initiated by pushing the INT 7 switch (which generates a RST 7), except when 
operating under DDI, in which case the DDI program gets control instead, 


Diskettes can be removed from the drives at any time, and the system can 
be shut down during operation without affecting data integrity, Note, 
however, that the user must not remove a diskette and replace it with another 
without rebooting the system (cold or warm start), unless the inserted 
diskette is "read only.” 


Due to hardware hang-ups or malfunctions, CP/M may type the message 
BDOS ERR ON x: BAD SECTOR 


where x is the drive which has a permanent error, This error may occur when 
drive doors are opened and closed randomly, followed by disk operations, or 
may be due to a diskette, drive, or controller failure, The user can 
optionally elect to ignore the error by typing a single return at the 
console, The error may produce a bad data record, requiring re-initialization 
of up to 128 bytes of data. The operator can reboot the CP/M system and try 
the operation again, 


Termination of a CP/M session requires no special action, except that it 
is necessary to remove the diskettes before turning the power off, to avoid 
random transients which often make their way to the drive electronics, 


It should be noted that factory-fresh IBM-compatible diskettes should be 
used rather than diskettes which have previously been used with any ISIS 
version, In particular, the ISIS “FORMAT” operation produces non-standard 
sector numbering throughout the diskette, This non-standard numbering 
seriously degrades the performance of CP/M, and will operate noticeably slower 
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than the distribution version, If it becomes necessary to reformat a diskette 
(which should not be the case for standard diskettes), a program can be 
written under CP/M which causes the MDS 8@@ controller to reformat with 
sequential sector numbering (1-26) on each track, 


CSP GED CES GN CD GD GE OME ae ee wo ED SED GRD 





Note: "MDS 800" and "ISIS" are registered trademarks of Intel Corporation, 
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1. AN OVERVIEW OF CP/M 2.0 FACILITIES. 


CP/4 2.9 is a high-performance single-console operating system 
which uses table driven tecnnigques to allow field recontiguration to 
match a wide variety of disk capacities, All of the fundamental file 
restrictions are removed, while maintaining upward compatiodility from 
previous versions of release-l1. Features of CP/M 2.@ include field 
specification of one to sixteen logical drives, eacn containing up to 
eignt megabytes. Any particular file can reacn the full drive size 
with the capaoility to expvand to thirty-two megabytes in future 
releases. The directory size can be field configured to contain any 
reasonable number of entries, and each file is optionally tagged with 
read/only and system attributes. Users of CP/M 2.39 are physically 
separated oy user numbers, with facilities for file copy operations 
from one user area to another. powerful relative-record random access 
functions are present in CP/M 2.9 which provide direct access to any 
of the 65536 records of an eight megabyte file. 


All disk-deovendent portions ot CP/M 2.9 are placed into a 
BIOS-resident “disk oarameter block" which is either nand coded or 
produced automatically using the disk definition macro library 
provided with CP/M 2.8. The end user need only specify the maximum 
numoer of active disks, the starting and ending sector numbers, the 
data allocation size, the maximum extent of the logical disk, 
directory size information, and reserved track values. The macros use 
this intormation to generate the appropriate taoles_ and table 
references for use during CP/M 2.8 operation. Deblocking information 
is also provided wnich aids in assembly or disassembly of sector sizes 
wnich are multivoles of tne fundamental 12% pyte data unit, and the 
system alteration manual includes general-purpose suoroutines which 
use the tnis deblocking information to take advantage of larger sector 
sizes. Use of these subroutines, togetner witn the table driven data 
access algoritnms, make CP/M 2.3 truly a universal data management 
system. 


File expansion is achieved by providing up to 512 logical tile 
extents, where eacn logical extent contains 16K bytes of data. CP/M 
2.0 is structured, nowever, so that as much as 128K bytes of data 15 
addressed by a single ohysical extent (corresponding to a single 
directory entry), thuS maintaining compatibility witn ovrevious 
versions while taking full advantage of directory space. 


Random access facilities are present in CP/M 2.06 whico allow 
immediate reference to any record of an eight megabyte file. Using 
CP/‘A's unique data organization, data blocks are only allocated when 
actually required and movement to a record position requires little 
search time. Sequential file access is uvward compatible from earlier 
versions LO tne full eignt megaoytes, wnile random access 
compatibility stops at 512K byte files. Due to CP/M 2.0’s simoler and 
faster random access, avplication orogrammers are encouraged to alter 
their programs to take full advantage of the 2.0 facilities. 


Several CP/M 2.0 modules ana utilities have imorovements which 
correspond to the ennanced file system. STAT and PIP both account for 
file attributes and user areas, while the CCP vrovides a “login” 
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| 


function to change from one user area to anotner, rhe» CCP also 
formats directory displays in a more convenient manner and accounts | 
for potn CRT and nard-coovy devices in its enhanced line editing | 
Functions, 


The sections pelow point out the individual differences between wy 
CP/M 1.4 and CP/M 2.8, with the understanding that the reader is 
eltner familiar witn CP/M 1.4, or has access to the 1.4 manuals. 
Additional information dealing with CP/M 2.9 I/O system alteration is | 
oresented in the Digital Research manual “CP/M 2.0 Alteration Guide." | 


EE ee 


—a —_ 
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2. USER INTERFACE, 


Console line processing takes CRI-type devices into account with 
three new control characters, shown with an asterisk in the list below 
(the sympol "ctl" below indicates tnat the control key is 
Simultaneously depressed) : 


rub/del removes and ecnoes last character 

ctl-C reboot when at beginning of line 

ctl-& physical end of line 

ctl-H vackspace one cnaracter position* 

ctl-J (line feed) terminates current input* 
ctl-M (carriage return) terminates invdut 
ctl-R retype current line after new line 
ctl-U remove current line after new line 
ctl-X backspace to beginning of current line* 


In particular, note tnat ctl-H produces the proper backspace overwrite 
function (ctl-H can be changed internally to another character, such 
as delete, through a simple single pyte change). Further, the line 
editor keeps track ot the current promot column position so that’ the 
operator can properly align data input following a ctl-U, ctl-R, or 
ctl-X command, 
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3. CONSOLE COMMAND PROCESSOR (CCP) IWTIERFACE, 


There are four functional ditferences between CP/M 1.4 and CP/M 
2.06 at the console command processor (CCP) level. The CCP now 
displays directory information across the screen (four elements per 
line), the USER command is present to allow maintenance of separate 
files in the same directory, and the actions of the "ERA *.*" and 
"SAVE" commands have changed, The altered DIR format is 
self-explanatory, while the USER command takes the form: 


USER n 


wnere n is an integer value in the range @ to 15. Upon cold start, 
the operator is automatically "logged" into user area number 6, which 
1s compatible with standard CP/M 1.4 directories. Tne operator may 
issue the USER command at any time to move to anotner liogical area 
within the same directory, Drives which are logged-in while 
addressing one user number are automatically active when the operator 
moves to another user numper since a user number is simply a prefix 
which accesses particular directory entries on the active disks. 


The active user number is maintained until changed by a 
Subsequent USER command, or until a cold start operation when user § 
1S again assumed, 


Due to the fact that user numbers now tag individual directory 
entries, tne ERA *.* command has a different effect, In version 1.4, 
this commana can be used to erase a directory wnicn has "garbage" 
information, verhnaps resulting from use of a diskette under another 
operating system (heaven forbid!). In 2.09, however, the ERA *,* 
command affects only the current user numoer. Tnus, it is necessary 
to write a simple utility to erase a nonsense disk (the vorogram simply 
writes the hexadecimal pattern E5 tnroughout the disk). 


The SAVE command in version 1.4 allows only a single memory save 
operation, with the potential of destroying the memory image due to 
directory operations following extent boundary changes. Version 2.9, 
nowever, does not verform directory operations in user data areas 
after disk writes, and thus the SAVE operation can be used any number 
of times without altering the memory image. 
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4. STAT ENHANCEMENTS. 


Tne STAT program nas a number of additional functions which 
allow disk parameter display, user number display, and file indicator 
manipulation. The command: 


STAT VAL: 


oroduces a Summary of the available status commands, resulting in the 
outpdout: 


Temo R/O Disk: d:=R/0 

Set Indicator: d:filename.typ $R/O SR/W SSYS SDIR 
Disk Status : DSK: d:DSK: 

User Status : USR:;: 

ITobyte Assign: 

(list of possible assignments) 


whicn gives an instant summary of the possible STAT commands. The 
command form: 
STAT d:filename.tyo $5 


wnere "d:" is an optional drive name, and "filename.typ" is an 
unambiguouS or ambiguous file name, orodguces the output disolay 
format: 


Size Recs Bytes Ext Acc 
43 48 6k 1 R/O A:ED,COM 
5» 55 12k 1 R/O (A:PIP.COM) 
65536 128 2k 2 R/W A:Xx.DAT 


where tne $S parameter causes the "Size" field to oe disvlayed 
(without the $55, the Size field is skipped, but the remaining fields 
are displayed). The Size field lists the virtual file size in 
records, while the "Recs" field sums the number of virtual records in 
each extent, For files constructed sequentially, the Size and Recs 
fields are identical. The “Bytes" field lists the actual number of 
bytes allocated to the corresponding file, The minimum allocation 
unit is determined at contiguration time, and thus tne number of bytes 
corresponds to the record count vlus the remaining unused space in the 
last allocated plock for sequential files, Random access files are 
given data areas only when written, so the Bytes field contains the 
only accurate allocation figure. In the case of random access, the 
Size field gives the logical end-of-file record position and the Recs 
field counts the logical records of each extent (each of these 
extents, however, may contain unallocated “noles" even though they are 
added into the record count). The "Ext" field counts the number of 
logical 16K extents allocated to the file. Unlike version 1.4, the 
Ext count does not necessarily correspond to the number of directory 
entries given to the file, since there can be uv to 128K pytes (8 
logical extents) directly addressed by a single directory entry, 
devending upon allocation size (in a special case, there are actually 
Z50K bytes which can be directly addressed by a ohysical extent). 


Tne “Acc" field gives the R/O or R/W access mode, which is 
changed using the commands shown pelow. Similarly, the parentheses 
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Shown around the PIP.COM file name indicate that it has the “system” 
indicator set, so that it will not be listed in DIR commands. the 
four command forms 


STAL d:tilename.typ $R/O 
STAT d:filename.tyo SR/wW 
STAT d:filename.typo $SyYS 
STAT d:filename.tyo SDIR 


set or reset various vermanent file indicators, The R/O indicator 
places the file (or set of files) ina read-only status until changed 
by a subsequent STAT command. The R/O status is recorded in the 
directory with tne file so that it remains R/O through intervening 
cold start operations, The R/W indicator places the file in a 
permanent read/write status. The SYS indicator attaches the system 
indicator to the file, while the DIR command removes the _ system 
indicator. The “filename.tyo" may be ambiguous or unambiguous, but in 
eitner case, the files wnose attributes are changed are listed at the 
console when the change occurs, The drive name denoted by "d:" is 
optional. 


When a file is marked R/O, Subsequent attempts to erase or write 
into the file result in a terminal BDOS message 


Bdos Err ond: File R/O 


The BOOS then waits for a console invut before performing a subsequent 
warm start (a “return” is sufficient to continue). The command form 


STAT d:DSK: 


lists the drive characteristics of the disk named by “d:" which is in 
the range As, B:, ..., P:. The drive characteristics are listed in 
the format: 


d: Drive Characteristics 
65536: 128 Byte record Capacity 
8192: Kilopyte Drive Capacity 
128: 32 Byte Directory Entries 
0: Checked Directory Entries 
1024: Records/ Extent 
128: Records/ Block 
58: Sectors/ Track 
2: Reserved Tracks 


where “d:" is the selected drive, followed by the total record 
capacity (65536 is an 8 megabyte drive), followed by the total 
Capacity listed in Kilobytes. The directory size is listed next, 
followed by the “checked" entries, The number of checked entries is 
usually identical to the directory size for removable media, since 
this mechanism is used to detect changed media during CP/M operation 
witnout an intervening warm start, For fixed media, the number is 
usually zero, since the media is not changed without at least a cold 
Or warm start. The number of records per extent determines’ the 
addressing capacity of each directory entry (1024 times 128 pytes, or 
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128K in the example above). The number of records ver block shows the 
basic allocation size (in the example, 128 records/plock times 128 
bytes per record, or 16K pytes per block). The listing is then 
followed by the number ot physical sectors ver track and the number of 
reserved tracks. For logical drives whicn share tne same physical 
disk, the number of reserved tracks may be quite large, since this 
mechanism is used to skio lower-numbered disk areas allocated to other 
logical disks. The command form 


STAT DSK: 


eroduces a drive characteristics table for all currently active 
drives. The final STAT command form is 


STAT USR: 


which produces a list of the user numbers whicn have files on the 
currently addressed disk. ne display format is: 


Active User : @ 
Active Files: @1 3 


where tne first line lists the currently addressed user number, as set 
by tne last CCP USER command, followed by a list of user numbers 
scanned from the current directory. In the above case, the active 
user numper is ¥ (default at cold start), witn three user numbers 
whicn nave active files on the current disk. The operator can 
Subsequently examine tne directories of the other user numbers by 
logging-in with USER 1, USER 2, or USER 3 commands, followed by a DIR 
command at the CCP level. 
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5. PIP ENHANCEMENTS. 


PIP provides three new functions which account for the features 
of CP/M: 258. All three functions take the form of file parameters 
which are enclosed in square prackets following the appropriate file 
names. The commands are: 


Gn Get File from User number n 
(n in the range 6 - 15) 


W Write over R/O files without 
console interrogation 


R Read system files 


The G command allows one user area to receive data files from another. 
Assuming the operator has issued the USER 4 command at the CCP level, 
the PIP statement 


PIP X.Y = X.Y[G2] 


reads file X.Y from user number 2 into user area number 4, The 
command 


PIP A:=A:*,* [G2] 


copies all of tne files from the A drive directory for user number 2 
into the A drive directory of the currently logged user number, Note 
that to ensure file security, one cannot copy files into a different 
area than the one which is currently addressed by the USER command. 


Note also that the PIP program itself is initially copvied to a 
user area (so that subsequent files can be copied) using the SAVE 
command, The sequence of operations shown below effectively moves PIP 
From one user area to the next. 


USER Jv login user g 

DDT PIP.COM load PIP to memory 
(note PIP size s) 

GY return to CCP 

USER 3 login user 3 


PAVE) Sy PLE, COM 


where s is the integral number of memory "pages" (256 byte segments) 
occupied by PIP. The number s can be determined when PIP.COM is 
loaded under DDT, by referring to the value under the "NEXT" display. 
If for example, the next available address is 1D#0, then PIP.COM 
requires 1C hexadecimal pages (or 1 times 16 + 12 = 28 pages), and 
thus the value of s is 28 in the subsequent save. Once PIP is copied 
in this manner, it can then be copied to another disk belonging to the 
Same user number through normal pip transfers, 


Under normal operation, PIP will not overwrite a file which is 


set to a permanent R/O status. If attempt is made to overwrite a R/O 
file, the prompt 
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NFSTINATION FILE IS R/O, DELETE (Y/N)? 


is issued. If the operator responds with the character "y" then the 
file is overwritten. Otnerwise, the response 


** NOT DELETED: ** 


is issued, the file transfer is skippped, and PIP continues with the 
next operation in sequence. In order to avoid the prompt and response 
in the case of R/O file overwrite, the command line can include the w 
parameter, as shown below 


PIP A:=8:* ,COM[w] 


which copies all non-system files to.the A drive from the 8 drive, and 
overwrites any R/O files in the process, If the operation involves 
several concatenated files, the W parameter need only be included witn 
the last file in the list, as shown in the following example 


PIP A.DAT = 8.DAT,F:NEW.DAT,G: OLD. DAT [WwW] 


Files with the system attribute can be included in PIP transfers 
if the R parameter is included, otherwise system files are not 
recognized. The command line 


PIP ED.,CUM = B:ED,CUM[R] 


for example, reads the ED.,COM file from the 8 drive, even if it has 
been marked as a R/O ana system file. The system file attributes are 
copied, if present. 


It should pe noted that downward compatibility with previous 
versions of CP/M is only maintained if the file does not exceed one 
megabyte, no file attributes are set, and the file is created by user 
0. If comoatibility is required with non-standard (e.g., “double 
density") versions of 1.4, it may be necessary to select 1.4 
compatibility mode when constructing the internal disk parameter plock 
(see tne “CP/M 2.8 Alteration Guide," and refer to Section 10 which 
describes BIOS differences). 
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oOo. ED ENHANCEMENTS. 


The CP/M standard orogram editor provides several new facilities 
in the 2.@ release. #xperience has shown that most operators use the 
relative line numbering feature of ED, and thus the editor has the "v" 
(Verity Line) option set as an initial value. The operator can, of 
course, disable line numbering by typing the "-v" command. If you are 
not familiar with the ED line number mode, you may wish to refer to 
tne Appendix in the sD user's guide, where the "v" command is 
described, 


ED also takes file attributes into account, If the operator 
attempts to edit a read/fonly file, the message 


** FILE IS READ/ONLY ** 


appears at the console, The file can be loaded and examined, but 
cannot be altered in any way. Normally, the operator simply ends the 
edit session, and uses STAT to change the file attribute to R/W. EE 
the edited file nas the "system" attribute set, the message 


“SYSTEM” FILE NOT ACCESSIBLE 
1s displayed at the console, and the edit session is aborted, Again, 
the STAT program can be used to change the system attribute, if 


desirea, 


Finally, the insert mode ("i") command allows CRT line editing 
functions, as described in Section 2, above, 
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7. THE XSUB FUNCTION, 


An additional utility program is supplied with version 2.9 of 

o\ CP/M, called XSUB, which extends the power of the SUBMIT facility to 

include line input to programs as well as the console command 

processor, The xXSUB command is included as the first line of your 

Submit file and, when executed, self-relocates directly below the CCP, 

All subsequent submit command lines are processed by XSUB, so that 

programs which read buffered console input (BDOS function 18) receive 

their input directly from the submit file. For example, the file 
SAVER.SUB could contain the submit lines: 


SAVE 1 $2.COM 

with a subsequent SUBMIT command: 
SUBMIT SAVER X Y 
which substitutes X for $1 and Y for $2 in the command stream. The 
XSUB program loads, followed by DDT which is sent the command lines 
“IX HEX" "“R" and “G@" thus returning to the CCP, The final command 
“SAVE 1 Y.COM" is processed by the CCP. 
loa’ The XSUB program remains in memory, and prints the message 

(xsub active) 
On each warm start operation to indicate its presence, Subsequent 
Submit command streams do not require tne XSUB, unless an intervening 


cold start has occurred. Note that XSUB must be loaded after DESPOOL, 
if both are to run simultaneously. 
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8. BDOS INTERFACE CONVENTIONS, 


CP/M 2.8 system calls take place in exactly the same manner as 
earlier versions, with a call to location @@05H, function number in 
register C, and information address in register pair DE. Single byte 
values are returned in register A, with double byte values returned in 
HL (for reasons of compatibility, register A = L and register B =H 
upon return in all cases). A list of CP/M 2.98 calls is given below, 
with an asterisk following functions whicn are either new or revised 
from version 1.4 to 2.0. Note that a zero value is returned for 
out-of range function numbers, 


J System Reset 19* Delete File 

1 Console Input 26 Read Sequential 

2 Console Output 21 write Sequential 

3 Reader Input 22* Make File 

4 Puncn Output 23* Rename File 

>. bISt Output 24* Return Login Vector 

6* Direct Console I/O 25 Return Current Disk 

7 Get I/O Byte 26 Set DMA Address 

38 Set I/O Byte 27 Get Addr (Alloc) 

9 Print String 28* Write Protect Disk 
19* Read Console Buffer 29* Get Addr(R/O Vector) 
11 Get Console Status 30* Set File Attributes 
12* Return Version Number 31* Get Addr(Disk Parms) 
13 Reset Disk System 32* Set/Get User Code 
14 Select Disk 33* Read Random 
15* Oven File 34* Write Random 
16 Close File 35* Comoute File Size 
17* Search for First 36* Set Randaom Record 


18* Searcn for Next 


(Functions 28, 29, and 32 should be avoided in application programs to 
maintain upward compatibility with MP/M.) The new or revised functions 
are described below. 


Function 6: Direct Console I/0. 


Direct Console I/0 is supported under CP/M 2.8 for those 
applications where it is necessary to avoid the BDOS console I/O 
operations. Programs whicn currently perform direct I/O tnrougn the 
BIOS should be cnanged to use direct I/O under sDOS so that they can 
be fully supported under future releases of MP/M and CP/M. 


Upon entry to function 6, register & eitner contains hexadecimal 
FF, denoting a console input request, or register & contains an ASCII 
Character. If the input value is FF, then function 6 returns A = #¥ 
if no character is ready, otherwise A contains the next console input 
character, 


If the inout value in £ is not FF, then function 6 assumes’ that 
£& contains a valid ASCII character which is sent to the console, 
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Function 108: Read Console Buffer. 


The console buffer read overation remains unchanged except that 

™ console line editing is supported, as described in Section 2. Note 

also that certain functions which return the carriage to the leftmost 

oosition (e.g., ctl-X) do so only to the column position where the 

promot ended (previously, the carriage returned to the extreme left 

margin). This new convention makes operator data input and line 
correction more legible, 


Function 12: Return Version Number. 


Function 12 has been redefined to orovide information which 
allows version-independent pvrogramming (this was previously the "lift 
head“ function whicn returned HL=00089 in version 1.4, but performed no 
operation). The value returned by function 12 is a two-byte value, 
with H = @@ for the CP/M release (H = @1 for MP/M), and L = 99 for all 
releases previous to 2.90. CP/M 2.9 returns a hexadecimal 20 in 
register L, with subsequent version 2 releases in the hexadecimal 
range 21, 22, through 2F. Using function 12, for examole, you can 
write apvplication programs which provide botn sequential and random 
access functions, with random access disabled when operating under 
early releases of CP/M. 


In the file operations described below, DE addresses a file 

control olock (FCB). Further, all directory operations take place in 

am a reserved area which does not affect write puffers as was the case in 

) version 1.4, with the exception of Searcn First and Search Next, where 
compatibility is required. 


The File Control Block (FCB) data area consists of a sequence of 33 
bytes for sequential access, anda series of 36 bytes in tne case that 

tne file 1S accesseaq ranaomly. The default file control block 
normally located at §W¥5CH can be used for random access files, since 
bytes W97DH, WYYU7EH, and 6@7FH are available for this purpose. For 
notational ourposes, the FCB format is shown with the following 
fields: 
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Wi 01 82 
where 


ar 


ree 


CLVEZ FCS 


ex 


sl 


S2 


rc 


dg...dn 


cr 


ryyrl,rZ 


OS O981O Li-f2e13-124 15726° oss 


ve coae (§ - 16) 

> use default drive for file 
> auto disk select drive A, 
> auto disk select drive B, 
auto disk select drive P, 


in ASCII 
bit = @ 


contain the file name 
upper case, with high 
contain the file type in ASCII 
upper case, with high bit = 9g 
tl’, t2’, and t3° denote the 

bit of these positions, 

tl’ = 1 => Read/only file, 

t2’' = 1 => SYS file, no DIR list 


the 
set 
y= 


contains 
normally 
in range 


current extent number, 
to 00 by the user, but 
31 during file I/O 
reserved for internal system use 
reserved for internal system use, set 
to zero on call to OPEN, MAKE, SEARCH 


record count for extent "ex,” 
takes on values from @ - 128 


filled-in by CP/M, reserved for 
system use 


current record to read or write in 
a sequential file overation, normally 
set to zero by user 


optional random record number in the 
range #§-65535, with overflow to r2, 
r@,rl constitute a 16-bit value with 
low byte r@, and high byte rl 


Function 15: Open File. 


Tne Open File operation is identical 
exception 
previous versions of CP/M defined this 


with the 


to 


byte as 


previous 
that byte s2 is automatically zeroed. 


zero, 


Sf 32> 33-3455 


definitions, 
Note that 


but made no 
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cneckS tO asSure compliance, Thus, the byte is cleared to ensure 
upward compatibility with the latest version, where it is required. 


Function 17: Searcn for First, 


Search First scans the directory for a match with the file given 
oy tne FCB addressed by ODE. The value 255 (hexadecimal FF) is 
returned if the file is not found, otherwise a value of A egual to 6, 
1, 2, or 3 is returned indicating the file is present. In the case 
tnat the file is found, the current DMA address is filled with the 
record containing the directory entry, and the relative starting 
position is A * 32 (i.e., rotate the A register left 5 bits, or ADD A 
five times). Although not normally required for application programs, 
tne directory information can be extracted from the buffer at this 
position, 


An ASCII question mark (63 decimal, 3F hexadecimal) in any 
position from fl through ex matches the corresponding field of any 
directory entry on the default or auto-selected disk drive. If the dr 
field contains an ASCII question mark, then the auto disk select 
function is disadled, the default disk is searched, with the search 
function returning any matched entry, allocated or free, belonging to 
any user number, This latter function is not normally used by 
application programs, out does allow complete flexibility to scan all 
current directory values. If the dr field is not a question mark, the 
s2 byte 1S automatically zeroed. 


Function 18: Search for Next, 


The Searcn Next function is similar to the Search First 
function, except that the directory scan continues from the last 
matched entry. Similar to function 17, function 18 returns’ the 
decimal value 255 in A when no more directory items match, 


Function 19: Delete File, 


The Delete File function removes files whicn match the FCB 
addressed by DE. The filename and type may contain ambiguous 
references (1.e., question marks in various positions), but the drive 
select code cannot be ambiguous, as in the Search and Search Next 
functions, 


Function 19 returns a decimal 255 if the reference file or files 
could not be found, otherwise a value in the range 9 to 3 is returned, 
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Function 22: Make File, 


The Make File operation is identical to previous versions of 
CP/M, except that byte s2 is zeroed upon entry to the 8DO0S. 


Function 23: Rename File, 


The Actions of the file rename functions are the same as 
previous releases except that the value 255 is returned if the rename 
function is unsuccessful (the file to rename could not be _ found), 
otherwise a value in the range ¥ to 3 is returned, 


Function 24: Return Login Vector, 


The login vector value returned by CP/M 2.8 is a 16-bit value in 
HL, where the least significant bit of L corresponds to the first 
drive A, and the high order bit of H corresponds to the sixteenth 
drive, labelled P. Note that compatibility is maintained with earlier 
releases, Since registers A and L contain the same values upon return, 


Function 28: Write Protect Current Disk. 


The disk write protect function provides temvoorary write 
protection for the currently selected disk. Any attempt to write to ud 
the disk, before the next cold or warm start operation produces the 
message 


Bdos Err on d: R/O 


Function 29: Get R/O Vector. 


Function 29 returns a bit vector in register pair HL which 
indicates drives which have the temporary read/only bit set. Similar 
to function 24, tne least significant pit corresponds to drive A, 
while the most significant bit corresponds to drive P. The R/O bit is 
set either: by an explicit call to function 28, or by the automatic 
software mechanisms within CP/M whicn detect changed disks. 


Function 38: Set File Attributes, 


The Set File Attributes function allows programmatic 
manipulation of permanent indicators attached to files. In 
particular, the R/O and System attributes (tl' and t2' above) can _ be 
set or reset, The DE pair addresses an unambiguous file name with the 
appropriate attributes set or reset, Function 3@ searches for a 
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matcn, and changes the matched directory entry to contain the selected 
inaicators, Indicators fl’ through £4' are not owresently used, but 
may be useful for applications programs, since they are not involved 


f in the matching orocess during file open and close operations. 
Indicators £5'° tnrough f38' and t3' are reserved for future system 
expansion. 


Function 3l: Get Disk Parameter Block Address, 


The address of the BIOS resident disk parameter block is 
returned in AL as a result ot this function call. This address can be 
used for either of two purposes, First, the disk parameter values can 
be extracted for display and space computation purposes, or transient 
programs can dynamically change the values of current disk parameters 
when the disk environment changes, if required. Wormally, avvlication 
programs will not require this facility. 


Function 32: Set or Get User Code, 


An application program can change or interrogate the currently 
active user number py calling function 32, If register E— = FF 
nexadecimal, tnen tne value of the current user number is returned in 
register A, where the value is in the range J to 31. If register E is 
not FF, then the current user number is changed to the value of §£ 

TN (modulo 32). 


Function 33: Read Random, 


The Read Random function is similar to the sequential file read 
Operation of orevious releases, except that tne read operation takes 
olace at a particular record number, selected by the 24-bit value 
constructed from the three pyte field following the FCB (byte 
oositions r@ at 33, rl at 34, and r2 at 35). Note that the sequence 
of 24 pits is stored with least significant byte first (r¥J), middle 
byte next (rl), and high byte last (r2). CP/M release 2.08 does not 
reference byte r2, except in computing the size of a file (function 
35). Byte r2 must be zero, however, since a non-zero value indicates 
overflow past the end of file. 


fnus, in version 2.0, the rW,rl byte pair is treated as a 
double-byte, or “word” value, which contains the record to read. This 
value ranges from 6 to 65535, providing access to any particular 
record of the 8 megabyte file. In order to orocess a file using 
random access, the base extent (extent WJ) must first be opened, 
Although the pase extent may or may nat contain any allocated data, 
tnis ensures that the file is oroperly recorded in the directory, and 
1s visible in DIR requests. The selected record number is then stored 
into the random record field (rd,rl), and the BDOS is called to read 

‘c™ tne record, Upon return from the call, register A either contains an 
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error code, as listed below, or the value 38 indicating the overation 
was successful. In the latter case, the current DMA address contains 
tne randomly accessed record, Note that contrary to the sequential 
reaaq operation, the record number is not advanced. Thus, suosequent 
random read operations continue to read the same record, Naw 


Upon eacn random read operation, the logical extent and current 


record values are automatically set. Thus, the file can be 
sequentially read or written, starting from the current randomly 
accessed position, Note, however, that in this case, the last 


randomly read record will be re-read as you switch from random mode to 
sequential read, and the last record will be re-written as you switch 
to a sequential write operation, You can, of course, simply advance 
tne random record position following each ranaom read or write to 
Obtain the effect of a sequential I/O operation. 


Error codes returned in register A following a random read are 
listed below. 


G1 reading unwritten data 

82 (not returned in random mode) 
083 cannot close current extent 

J4 seek to unwritten extent 

Y¥5 (not returned in read mode) 

60 seek past ohysical end of disk 


Brror coGce wl ana w4 occur when a random read operation accesses a 

gata plock which has not been previously written, or an extent which 

nas not been created, which are equivalent conditions. Error 3 does 

not normally occur under proper system operation, but can be cleared | 

by simply re-reading, or re-opening extent zero as long as the disk is ~~ 
not physically write vrotected. Error code 896 occurs whenever byte r2 

is non-zero under the current 2.9 release, Normally, non-zero return 

codes can be treated as missing data, with zero return codes 
indicating overation complete, 


Function 34: Write Random, 


The Write Random operation is initiated similar to the Read 
Random call, except that data is written to the disk from the current 
DMA address, Further, if the disk extent or data block which is’ the 
target of the write nas not yet been allocated, the allocation is 
performed before the write operation continues, AS in the Read Random 
operation, the random record number is not changed as a result of the 


write, The logical extent number and current record positions of the 
file control block are set to corresvond to the random record which is 
being written, Again, seguential read or write operations can 


commence following a random write, with the notation that’ the 
currently addressed record is either read or rewritten again as_ the 
sequential operation begins. You can also simply advance the random 
record position following each write to get the effect of a sequential 
write operation, Note that in particular, reading or writing the last 
record of an extent in random mode does not cause an automatic extent 
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switch as it does in seguential mode under either CP/M 1.4 or CP/M 
a0. 


Tne error codes returned by a random write are identical to’ the 
random read operation with the addition of error code 45, wnich 
indicates that a new extent cannot be created due to directory 
overflow. 


Function 35: Compute File Size. 


When computing the size of a file, the DE register pair 
addresses an FCB in random mode format (bytes r@, rl, and r2 are 
present). The FCB contains an unambiguous file name which is used in 
the directory scan. Upon return, the random record bytes contain the 
“virtual” file size wnich is, in effect, the record address of the 
record following tne end of the file. if, following a call to 
function 35, the high record byte r2 is 01, then the file contains the 
maximum record count 65536 in version 2.8. Otherwise, bytes rd and rl 
constitute a 16-bit value (rd is the least significant pyte, as 
before) which is the file size, 


Data can be appended to tne end of an existing file by simoly 
calling function 35 to set the random record position to the end of 
file, tnen overforming a sequence of random writes starting at the 
preset record address, 


Tne virtual size of a file corresponds to the physical size when 
the file is written sequentially. If, instead, the file was created 
in random mode and “holes” exist in the allocation, then the file may 
in fact contain fewer records than the size indicates. If, f0% 
example, only the last record of an eight megabyte file is written in 
random mode (i.e., record number 65535), then the virtual size is 
65536 records, although only one block of data is actually allocated. 


Function 36: Set Random. Record. 


The Set Random Record function causes the BDOS to automatically 
produce the random record position from a file which nas been read or 
written sequentially to a varticular. point. The function can be 
useful in two ways. 


First, it is often necessary to initially read and scan a 
Sequential file to extract the positions of various “key” fields. As 
each key is encountered, function 36 is callea to compute the random 
record position for the data corresponding to this key. If the data 
unit size is 128 pytes, the resulting record vosition is placed into a 
table with the key for later retrieval. After scanning the entire 
file and tabularizing the keys and their record numbers, you can move 
instantly to a particular keyed record by performing a random read 
uSing the corresponding random record number which was saved earlier. 
The scheme is eaSily generalized when variable record lengths are 
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involved since the program need only store the buffer-relative byte 
position along with the key and record number in order to find the 
exact starting position of the keyed data at a later time. 


A second use of function 36 occurs when switching from a 
seguential read or write over to random read or write. A file is 
sequentially accessed to a particular point in the file, function 36 
is called whicn sets the record number, and subsequent random read and 
write operations continue from the selected point in the file. 


This section is concluded with a rather extensive, put complete 
example of random access operation, The program listed below performs 
the simple function of reading or writing random records upon command 
from the terminal. Given that the program has been created, 
assembled, and placed into a file labelled RANDOM.COM, the CCP level 
command: 


RANDOM X.DAT 


Starts the test program. The program looks for a file by the name 
X.DAT (in this particular case) and, if found, proceeds to prompt the 
console for input. If not found, the file is created before the 
orompt 1S given. Each prompt takes the form 


next command? 


and is followed by operator input, terminated by a carriage return. 
The inout commands take the form 


nw NnR Q 


where n is an integer value in the range J to 65535, and W, R, and Q 
are simple command characters corresponding to random write, random 
read, and quit processing, resvectively. If the W command is issued, 
the RANDOM program issues the prompt 


type data: 


The operator then responds by typing up to 127 characters, followed by 
a carriage return. RANDOM then writes the character string into the 
X,.ODAT file at record n. If the R command is issued, RANDOM reads 
record number n and displays the string value at the console. If the 
Q command is issued, the X.DAT file is closed, and the program returns 
to the console command processor, In the interest of brevity (ok, so 
the program's not so brief), the only error message is 


error, try again 
The orogram begins with an initialization section where the 
input file is opened or created, followed by a continuous loop at the 
label "ready" where the individual commands are interpreted. The 
default file control block at 9@5CH and the default buffer at #080H 
are used in all disk operations, The utility subroutines then follow, 
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which contain the principal inout line processor, called "“readc." 
This particular program shows the elements of random access 
processing, and can be used as the basis for further program 
development. 


e KKKKKKKKKKEKKKKKKKKKKEKKKKKKKKKKKEKKKEKKKKEKKKKKEKKKKKEKKK 


ox * 
7* sample random access vrogram for cyo/m 2.9 * 
x * 
CROCCO ICICI IOC ICICI ICICI COCCI CIO ICI III TOOK 

0109 org 10h sbase of tva 

GOdU = reboot edu O0900h system reboot 

0005 = bdos equ 8905h ;odos entry point 
7 

¥OU1 = coninp egu 1 console input function 

0002 = conout equ 2 sconsole output function 

OGWY9 = ostring equ 9 sprint string until *S"’ 

00a = rstring eau 1¥ eread console buffer 

v0UC = version equ iz ;return version number 

JOULE = openf equ 1:5 ;file open function 

WJ19 = closef equ 16 «close function 

G016 = makef equ a2 smake file function 

JU2Z1 = readar equ 33 ;read random 

Jv22 = writer eau 34 swrite random 

J¥5c = oe @. equ ¥i5ch sdefault file control block 

GJ7d = ranrec equ fcb+33 +s:random record position 

vd7£ = ranov£ equ. fcot35 -s;nigh order (overflow) byte 

BV8d = buff equ Jd8vh sbuffer address 

O00Jd = oe 4 equ Ydh carriage return 

Woda = 1f equ Wah sline feed 
DOIG ICO TICIGIIIOO ICICI TIC TICICIGIICICOITICICIGI ICICI IG OCK 
x * 
;* load SP, set-up file for random access x 
ox * 
ICICI RICCO ICICI ICCC IOICCICTOCIOICIOCICIO COICO II IC# 

Y1@8 3l1lbcd 1xi sp,stack 
; version 2.0? 

J1lv3 Vebc mvl c,version 

0105 cd¥5U call bdos 

0108 fe2d cpl 20n sversion 2.@ or better? 

Ylva d2166 jne versok 
. bad version, message and go back 

Hldd lllbd 1xi d,badver 

0118 cdda¥ Gaal orint 

J113 c3090 Jmo reooot 
versok: 
: correct version for random access 
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—————————————— — 


Jllo dvedt mV1 c,openf ;open default fcb 
Hl1l3s 115c9 Lxi GSECD 
Jllo cd¥v5¢ call bdos 
lle 3c inr a eerr 255 becomes zero 
OLLI c2370 jnz ready 

; cannot open file, so create it 
J1l22 Jelo Mv c,makef 
J124 115c¥ LxXi d2fcp 
J127 cdv5¥ call bdos 
Jl2a 3c in, a serr 255 becomes zero 
0120 c2370 jnz ready 

; cannot create file, directory full 
Jl2e ll3ad 1x1 d,nospace 
J131 cdadad call print 
J134 c39dd jmp reboot ;back to ccp 


RKEKEKEKKKKEKKKEKKEKKKKKKEKKEKKKEKEKKRKEKKEKEKKKKKKKKKKKKRKKEKK 


* * 
* looo back to “ready” after each command “i 
* * 


KRKRKKKKEKKKKKKKRKRKKEKEKKREKKEERKKEKEKKKEKEKRKEKKEKEKKEKKREKKEKEKE 


me =e FX te wo WO MO UNO RO NO 


eady: 
file is ready for processing 
W137 cdedy call readcom ;read next command 
Jl3a 227/dv shid ranrec ;store input record# 
Vl3d 217f% 1x1 h,canovt 
W146 30090 mv m,@ clear high byte if set 
0142 fe5l col 9 he ;quit? 
J144 c2568 jnz notg 
: quit processing, close file 
0147 deld mMVi1 c,closef 
0149 115c¥ 1xi oa oy 2 
Vl4c cdi5u call bdos 
WV14f 3c ine a eerr 255 becomes @ 
J158 cab9V Jz error serror message, retry 
0153 c3d00d jmo reboot :back to ccp 
DIGG ICICI CIOCI COGIC OOOO ICICI ICE K 
x * 
;* end of quit command, vorocess write 7 
ox * 
ETT ET TTT TT TI TTI TT TTT TTT TTT TTT tte rt ttt tt ttt ttt tty 
HOoOtg: 
. not the quit command, random write? 
9156 fe57 cpl ‘Ww 
9158 c2896 Inz notw 
; this is a random write, fill buffer until cr 
J15b 11448 Lea d,datmsg 
J1l5e cddag call print s;data prompt 


(All Information Contained Herein is Proprietary to Digital Research, ) 


22 





0161 de7£ mv c,127 sup to 127 characters 


0153 21800 1x1 n,outf sdestination 
rloop: ;read next character to buff 
¥166 c5 push b >save counter 
Jlo7 e5 push h snext destination 
J168 cac20 call getchr ;character toa 
Jloo el pop h restore counter 
vioc cl DOD fe) srestore next to fill 
Wloéd fetid Sor cr send of line? 
J1lot ca78d 1% erlooo 
: not end, store character 
OEP Ls Fd mov m,a 
V173 23 inx h *snext to fill 
J174 Wd acr c scounter goes down 
9175 c2660 jnz rloop -end of puffer? 
erloop: 
° end of read loop, store ¥Q@ 
¥178 3609 mv1 m,i 


=e we 


write the record to selected record number 


Jl7a We22 mvi c,writer 

Vl7c 115cd 1x1 d,fcb 

J17£ cde@5v call bdos 

J1l82 b/ ora a serror code zero? 
V1383 c2b98 jnz error smessage if not 
91386=¢033.70 jmp ready >for another record 


v 
o KKKEKKKKKEKKKEEKEKKEREREREREREKKRKKREKREKRKKEKKKEKEKEKREKRKREKE 


x * 
a ** end of write command, vorocess read * 

ex * 
DIOGO G OGG ISIOIO GIS CIOIOIGICIOICICICGIICIOI ICCC II ITC IOK 
notw: 
° not a write command, read record? 

Y189 fed2 cpl rR 

G1l8b c2b9H jnz error *skip if not 
; read random record 

J1l8e de2l mvi c,readr 

J190 115cB 1x1 d,fcb 

0193 cdd5d call bdos ~ 

9196 b7 ora a sreturn code gd? 

J197 c2b9¢ jnz error 
° read was successful, write to console 

919a cdcfd call crlf snew line 

019d ves mvi c,128 smax 128 characters 

W19f 21800 1xi h,buf£ ;next to get 
wloop: 

YJla2 Je mov a,m snext character 

Yla3 23 inx h snext to get 

Gla4 e67E£ anl 7£h ;maSk parity 

J1a6 ca37@ Jz ready ;for another command if 0@ 

Qla9 c5 push b save counter 

in’ laa e5 push h >Save next to get 
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Wlab fe20 cpl graphic? 


lad d4c3¢ Enc putchr ;skip output if not 

Ylbv el pov n 

A Bo am ot | pop b 

O@lb2 Oa dcr G ecount=count-l 

Ylb3 c2a2G jnz wloop 

Vlbo c3378 jmp ready 
ORIG CIOO ICI IC IOI ICICI COICO UICC COCCI COI ICICI II K 
0X * 
;* end of read command, all errors: end-uvo here ‘ 
* k 


KKEKEKKKKKEKKKRKEKKKKKEKRKRKEEKKEKEKKKEKREKKKEKKEKRKKKEKKEKKEKRKEKKERE 


=e “068 TWO 


error: 

HlbY 1159G bie at d,errmsg 

Olbc cddaJg call print 

Qlbf c3370 jmo ready 
7 
eo KRKRKKKKKEKKKKKKKKKKKKKKKKKKEKKKKKKKKKKRKEKKKEKKEKKKKKKRKKE 
2 % * 
7;* utility subroutines for console i/o * 
ox * 
a 
e RKKKKKKKKKKKKKKKEKKKKKKKEKKKKKKKKEKKKKEKKKKKKKKKKKKKKKK 
getchr: 

sread next console character toa 

Glc2 Bevl mvil Gy. conaino 

Ylc4 cdyg5v call bdos 

Jic/ cy ret 


7 
DUECHT s 
write character from a to console 


Vlc8 Yev2 mvi Sconou. 
Wlca 5f MOV e,a character to send 
Jlecb cdd5d call bdos *send character 
Jlce cY ret 
Chit: 
send carriage return line feed 
Wlcf 3e0d mv1 ayn *;Carriage return 
Jldl cdc8&¥g call putchnr 
YV1ld4 3eva mvi a,lf *line feed 
ldo cdc8¥d Cad putchr 
Qlay c9 ret 
print: 
sprint the buffer addressed by de until § 
Ylda d5 push d 
DQldbo cdcfs call er if 
Ylde dl pop d snew line 
Wlaf 0eb9 mvi c,pstrina 
Jlel cddé5@ call bdos sorint the string 
Wle4 c9 ret 


v 
readcom: 


(All Information Contained Herein is Proprietary to Digital Research.) 


24 


eread the next command line to the conbuf 





Ole5 116bd 1xi d,orompt 
Qle8 cdda¥g call print :command? 
Yleb Yeva mvi c,rstring 
Wled 1l7aw 1x1 d,conbuf 
@1f£0 cdd5u call bdos ;read command line 
; command line is present, scan it 
01£3 21000 1xi h,@ start with 9000 
G1f6 ll7cd 1x1 d,conlin;command line 
01f9 la reaac: ldax qd enext command character 
Jlfa 13 inx | sto next command position 
Vifb b7 ora a scannot be end of command 
Jltc c8 rz 
: not zero, numeric? 
Olfd d63v sul "9g ° 
Q1ff£ feva cpl 19 scarry if numeric 
Y201 d213d jne endrd 
: add-in next digit 
@204 29 dad h ,e2 
W205 4d MOV CG jal. 
@2v6 44 mov b,n sbc = value * 2 
§207 29 dad h 2*4 
9268 29 dad h 2 *8 
02099 89 dad b °*2 + *8 = *19 | 
Q@2¥a 85 add 1 s+digit | 
d2vo OL mov l,a | 
Q2dc a2f9v jne readc efor another char | 
d28f 24 inr h soverflow | 
W21lv c3f9V Jmp readc ;for another char | 
endrd: 
; end of read, restore value in a 
06213 c63W adi ga a -command 
89215 feol col a stranslate case? 
9217 d8 rc 
: lower case, mask lower case bits | 
9218 eb65f ani 101$1111l6 | 
92la c9 ret 
ICICI GIGI ICICI IOI IOI OIC Ik | 
x * 
;* string data area for console messages e 
7X * 
DIGIC ISOG UICC COGIC ICICOO IOC ICCC 
badver: 
W2Z2lbd 536f£79 db ’sorry, you need cp/m version 2S' 
nospace: 
W23a 4e6f£29 db "no directory spaces’ 
datmsg: 
624d 547979 db ‘type data: $' 
errmsg: 
9259 457272 db ‘error, try again.$' 
prompt: 
0266 4e€6570 db ‘next command? $' 


° 
g 
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O27a 
Y27b 
G2ZIC 
Jd21 
829c 


J Zoc 


a 





e RK KKKKKKKKKKKKKKKKKKKKKKKEKKEKKKKKKKKKKKKKKKEKKKKKEK SE 


ox * 
0 
>* fixed and variable data area a] 
ox * 
a 
e KKKKKKKKKKKKKKKKKKKEKKEKKKKKKEKKEKEREKKRKKKEKEKKEEKKKKKEK ‘ 7 
conbuf: db conlen ;length of console buffer 
consiz: ds 1 sresulting size after read 
conlin: ds 32 slength 32 buffer 
conlen equ S-consiz 
, 

ds 32 °16 level stack 
stack: 

end 
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9. CP/M 2.0 MEMORY ORGANIZATION, 


Similar to earlier versions, CP/M 2.0 is 
upon 


32k 
6400H 
6C% OH 
7AQ08 
7PPFFA 


The distribution disk contains a CP/M 2.9 system configured for a 
floppy disk drives. 


IBM 3" 


variouS memory sizes, depending 
configuration. Typical 
Shown in the tandle below. 
Module | 20k 24k 
CCP 3460H 4499H 
BDOS 3CWOYH 4C@ 9H 
BIOS 4A90 0H 5A0 0H 
Too of Ram 4FFFH 5SFFFH 
Intel MDS-800 with standard 
layout 1S shown below: 
Sector Track Jv Module 
if (Bootstrap Loader) 
2 34008 CCP + 8H 
3 343808 CCP + 980H 
4 35098 CCP + 100H 
5 358H CCP + 18H 
6 360 0H CCP + 206H 
7 36868 CCP + 28H 
rs 3 700i CCP + 30048 
Y 3730H CCP + 38H 
ly 380d CCP + 46H 
Ed 3388H CCP + 48H 
12 39004 CCP + 5@@H 
13 398WH CCP + 58H 
14 3A00H CCP + 60H 
15 3A86H CCP + 680H 
16 3B 9H CCP + 7008 
4 ae 3B30H CCP + 780H 
18 3C¥09H BDOS + @08H 
19 3C80H BDOS + @890H 
20 3D00H BDOS + 10H 
21 3D80H BDOS + 13H 
22 3E90H BDOS + 200H 
Ze 3E80H BDOS + 280H 
24 3F90H BDOS + 300H 
25 3F80H BDOS + 38H 
26 49009H BDOS + 400H 


Track 


4680H 
41008 
418048 
42008 
423U0H 
430048 
4330 
44608 
4480H 
45H 
45308 
4600H 
4680H 
4760H 
4780H 
4860H 
48804 
4900H 
498UH 
4A00H 
4A80H 
4B00H 
4B80H 
4COOH 
4C80H 
4D00H 


host 


48k 
A400H 
ACO OH 
BAIOH 
BFEFFH 


01 

BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BDOS 
BIOS 
BIOS 
BIOS 
BIOS 
BIOS 
BIOS 
BIOS 


t++eteteeeeteereteteegtertetetertrtettt 


field-altered to 
computer 
base addresses for popular memory sizes are 


64k 
E400H 
ECO GH 
FAQ 0H 
FFE FA 


Module 


480H 
5 00H 
58H 
600H 
680d 
7964 
780H 
890H 
8 80H 
990H 
980H 
AGH 
A89H 
BO OH 
B38@H 
COOH 
C8aH 
DOCH 
D8 OH 
HOOH 
§80H 
19H 
18@H 
200H 
2804 
309H 


In particular, note that the CCP is at the same position on the disk, 
and occupies the same space aS version 1.4. The BDOS portion, 
however, occupies one more 256-byte page and the BIOS portion extends 
through the remainder of track @l. Thus, the CCP is 8W0@H (2048 
decimal) bytes in length, the 8DOS is EQ@H (3584 decimal) bytes in 
length, and the BIOS is up to 38@H (898 decimal) bytes in length. In 
version 2.08, the BIOS portion contains the standard subroutines of 
1.4, along with some initialized table space, as described in the 
following section. 
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13. BIOS DIFFERENCES. 


The CP/M 2.6 Basic I/O System differs only slightly in concept 
from its predecesssors, Two new jumo vector entry points are defined, 
a new sector translation subroutine is included, and a disk | 
Characteristics table must be defined. The skeletal form of these ad 
changes are found in the program shown below, 


a org 4800h 

2: maclio diskdef 

a¢ jmo boot 

4: ; pce 

De jmp listst ;list status 

6: Jmpo sectran ;sector translate 

43 disks 4 

oss large capacity drive 

2 ¢ DOD equ 16*1924 s;bytes ver block 

10: rpb equ bpb/1238 ;records per block 

ll: maxb equ 05535/rood ;max block number 

12: diskdef @,1,58,3,bpb,maxb+1,128,9,2 

p3* diskdef 1,1,58, ,bpb,maxb+1,128,9,2 

14: diskdef 2,29 

15: diskdef 3,1 

LGs0% 
is, BOOS ret -nop 
Loss 

19: Listst: xra a -nop 

20: ret 

Zi. 3 

22: seldsk: 

23: sdrive number inc og 
24; 1x1 h,@ 0008 in hl produces select error 
25: MOv ait ea is disk number J ... ndisks-l 
26: Cpa. ndisks ;less than ndisks? 

27: rnc ereturn with HL = 0000 1£ not 
262% proper disk number, return dpb element address 
293 NOV i-sc 

30: dad h iat 

31% dad h 2 *4 
32: daa h 2 *8 

S25 daa h ¢*16 

34% Ee d,dpbase 
SO dad d ;HL=.dpb 

36s ret 

37s 3 

38: selsec: 

39: -sector number inc 

4d: 1x1 h,sector 

4l: mov 17 

42: ret 

43: ; 

44: sectran: 

45: translate sector BC using table at DE 

46: xchg 7-HL = .tran 

47: dad b Single orecision tran 


bd 
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483 ; dad b again if double precision tran 


49: mov 1,m only low byte necessary here 
as 3 fill botn H and L if double orecision tran 
51: ret eHL = ??ss 

iain Dees 
53: sector: ds 1 
54:3 endef 
3:3 end 


Referring to the program shown above, lines 3-6 represent the 
BIOS entry vector of 17 elements (version 1.4 defines only 15 jumo 
vector elements). The last two elements provide access to the 
“LISTST" (List Status) entry point for DESPOOL. The use of this 
particular entry point is defined in the DESPOOL documentation, and is 
no different than the previous 1.4 release, It should be noted that 
the 1.4 DESPOOL program will not operate under version 2.0, but an 
update version will be available from Digital Research in the near 
future, 


The “SECTRAN" (Sector Number Translate) entry shown in the jump 
vector at line 6 provides access to a 310S-resident sector translation 
Subroutine, This mechanism allows the user to specify the sector skew 
factor and translation for a particular disk system, and is described 
below. 


A macro library is shown in the listing, called DISKDEF, 
included on line 2, and referenced in12-15. Although it is not 
necessary to use the macro liorary, it greatly simplifies the disk 

mo detinition process. You must have access to the MAC macro assembler, 
of course, to use the DISKDEF facility, while the macro library 1s 
included with all CP/M 2.80 distribution disks. (See the CP/M 2.90 
Alteration Guide for formulas which you can use to hand-code the 
tables produced by the DISKDEF library). 


A BIOS disk definition consists of the following sequence of 
macro statements: 


MACLIB DISKDEF 
DISKS n 
DISKDEF 9@,... 
DISKDEF 1l1,... 
DISKDEF n-l 


ENDEF 


where the MACLIB statement loads the DISKDEF.LIB file (on the same 
disk as your BIOS) into MAC’s internal tables. The DISKS macro call 
follows, which specifies the number of drives to be configured with 
your system, where nis an integer in the range 1 to 16. A series of 
DISKDEF macro calls then follow which define the characteristics of 
each logical disk, #@ through n-l (corresvonding to logical drives A 
through P). Note that the DISKS and DISKDEF macros generate in-line 
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fixed data tables, and thus must be placed in a non-executabdle portion 
of your BIOS, typically directly following the BIOS jump vector. 


The remaining portion of your BIOS is defined following the 
DISKDEF macros, with the ENDEF macro call immediately preceding the 
END statement, The ENDEF (End of ODiskdef) macro generates’ the 
necessary uninitialized RAM areas which are located above your BIOS. 

The form of the DISKDEF macro call is 


DISKDEF adn,fsc,lsc,[skf],bls,dks,dir,cks,ofs, [G] 


where 
dn is the logical disk number, J to n-l 
fsc is the first physical sector number (@ or 1) 
lsc 1s the last sector number 
skf is the optional sector skew factor 
pls is the data allocation block size 
gir is the number of directory entries 
cks is the number of "checked" directory entries 
ots 1s the track offset to logical track d2@ 
[d ] is an ovtional 1.4 comvoatibility flag 


The value “dn" is the drive number being defined with this DISKDEF 


macro invocation. The "fsc" parameter accounts for differing sector 
numoering systems, and is usually 9 or l. The “lsc” ais the last 


numoered sector on a track. When present, the "skf£" parameter defines 
the sector skew factor which is used to create a sector translation 
table according to the skew. If the number of sectors is less’ than 
256, a single-byte table is created, otherwise each translation table 
element occupies two bytes. No translation table is created if the 
Sskf parameter is omitted (or equal to 9). The “bls“ parameter 
specifies the number of bytes allocated to each data block, and takes 
On the values 1024, 2048, 40896, 8192, or 16384, Generally, 
performance increases with larger data block sizes since there are 
fewer directory references and logically connected data records are 
physically close on the disk. Further, each directory entry addresses 
more data and the BIOS-resident ram space is reduced, The "“dks" 
specifies tne total disk size in "bls" units. That is, if the bls = 
2648 and dks = 1008, tnen the total disk capacity is 2,048,000 bytes. 
If dks is greater than 255, then the block size parameter bls must be 
greater than 14924, The value of "“dir" is the total number of 
directory entries which may exceed 255, if desired. The "“cks" 
parameter determines the number of directory items to check on each 
directory scan, and is used internally to detect changed disks during 
System operation, where an intervening cold or warm start has not 
occurred (when this situation is detected, CP/M automatically marks 
the disk read/only so that data is not subsequently destroyed). 
Normally the value of cks = dir when the media is easily changed, as 
is the case with a floppy disk subsystem, If the disk is permanently 
mounted, then the value of cks is typically #@, since the probability 
of changing disks without a restart is guite low. The "ofs" value 
determines the number of tracks to skip when this particular drive is 
addressed, which can be used to reserve additional operating system 
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space or to simulate several logical drives on a single large capacity 
physical drive. Finally, the [@] parameter is included when file 
compatibility is required with versions of 1.4 which have been | 
modified for higher density disks. This parameter ensures that only | 

ce” 16K is allocated for each directory record, as was the case for 
previous versions. Normally, this parameter is not included. 








For convenience and economy of table svace, the special form | 
DISKDEF ee 


gives disk i the same characteristics as a previously defined drive j. 
A standard four-drive single density system, which is compatible with 
version 1.4, is defined using the following macro invocations: 


DISKS 4 
DISKDEF 4) 
DISKDEF 1 
DISKDEF 2 
DISKDEF 3 


,26,6,1024,243,64,64,2 





ENDEF 


with all disks having the same varameter values of 26 sectors per | 
track (numbered 1 through 26), with 6 sectors skipped between each 
access, 1024 bytes per data block, 243 data blocks for a total of 243k 
byte disk capacity, 64 checked directory entries, and two operating 
system tracks. 

The definitions given in the program shown above (lines 12 | 
through 15) provide access to the largest disks addressable by CP/M | 
2.0. All disks have identical parameters, except that drives @ and 2 
skip three sectors on every data access, while disks 1 and 3 access | 
each sector in sequence as the disk revolves (there may, however, be a | 
transparent hardware skew factor on these drives). 





The DISKS macro generates n “disk header blocks," starting at 
address DPBASE which is a label generated by the macro, Each disk 

header block contains sixteen bytes, and correspond, in sequence, to | 
each of the defined drives. In the four drive standard system, for 
example, the DISKS macro generates a table of the form: 
| 


DPBASE EQU $3 

DPE@: DW XLTO,29000H,0000H,9090H,DIRBUF ,DPBI,CSV9 ,ALVO 

DPE1: DW XLTY ,O000H,YV090H,O8VVOH,DIRBUF,DPBY,CSV1,ALV1 

DPE2: DW XLTO ,6090H,0000H,0000H,DIRBUF,DPB9,CSV2,ALV2 

DPE3: DW XLTO ,@990H,0900H,0000H,DIRBUF,DPBY,CSV3,ALV3 | 
| 


where the DPE (disk parameter entry) labels are included for reference 
purposes to show the beginning table addresses for each drive @Q 
through 3. The values contained within the disk parameter header are 
described in detail in the CP/M 2.@ Alteration Guide, but basically | 
address the translation vector for the drive (all reference XLTO, | 
which is the translation vector for drive @ in the above example), | 
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followed by three 16-bit "scratch" addresses, followed by the 
directory buffer address, cdisk parameter block address, check vector 
address, and allocation vector address, The check and allocation 
vector addresses are generated by the ENDEF macro in the ram area 
following the BIOS code and tables, 


The SELDSK function is extended somewhat in version 2.90. In 
particular, the selected disk number is passed to the BIOS in register 
C, aS before, and the SELDSK subroutine performs the appropriate 
software or hardware actions to select the disk, Version 2.4%, 
however, also requires the SELDSK subroutine to return the address of 
the selected disk parameter header (DPE®, DPE1, DPE2, or DPE3, in the 
above example) in register dL, If SELDSK returns the value HL = 
0000H, then the BDOS assumes the disk does not exist, and prints a 
select error mesage at the terminal. Program lines 22 through 36 give 
a sample CP/M 2.@ SELDSK subroutine, showing only the disk parameter 
header address calculation, 


The subroutine SECTRAN is also included in version 2.9 which 
performs the actual logical to physical sector translation. In 
earlier versions of CP/M, the sector translation process was a part of 
the BDOS, and set to skip six sectors between each read, Due 
differing rotational speeds of various disks, the translation function 
has become a ovart of the BIOS in version 2.6. ‘Thus, the BDOS sends 
sequential sector numbers to SECTRAN, starting at sector number JQ, 
The SECTRAN subroutine uses the seguential sector number to produce a 
translated sector number which is returned to the B8DOS. The  BDOS 
Subsequently sends the translated sector number to SELSEC before the 
actual read or write is verformed, Note that many controllers have 
the capability to record the sector skew on the disk itself, and thus 
there is no translation necessary. In this case, the “skf" parameter 
1S omitted in the macro call, and SECTRAN simply returns the same 
value which it receives. The table shown below, for example, is 
constructed when the standard skew factor skf = 6 is specified in the 
DISKDEF macro call: : 


XLT@: DB Lgl pL Sple yLOPOV els LigZe yop yee 
DB 2,8,14,20;,26,6,12,18,24,4,10,16,22 


If SECTRAN 1S required to translate a sector, then the following 
process takes place. Tne sector to translate is received in register 
pair BC. Only the C register is significant if the sector value does 
not exceed 255 (B = @@ in this case). Register pair DE addresses’ the 
sector translate table for this drive, determined by a previous call 
on SELDSK, corresponding to the first element of a disk parameter 
header (XLTO in the case shown above). The SECTRAN subroutine then 
fetches the translated sector number by adding the input sector number 
to the base of the translate table, to get the indexed translate table 
address (see lines 46, 47, and 48 in the above program). The value at 
this location is then returned in register L, Note that if the number 
of sectors exceeds 255, the translate table contains 16-bit elements 
whose value must be returned in HL, 


Following the ENDEF macro call, a number of uninitialized data 
areaS are defined. Tnese data areas need not be a part of the BIOS 
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which is loaded upon cold start, but must be available between the 
BIOS and the ena of memory. The size of the uninitialized RAM area is 
determined by EQU statements generated by tne ENDEF macro, For a 
standard four-drive system, the ENDEF macro might vroduce 


4C72 = BEGDAT EQU $ 
(data areas) 
40B0 = ENDDAT EQU 5 
H13C = DATSIZ EQU $S-BEGDAT 


which indicates that uninitialized RAM begins at location 4C72H, ends 
at 4DBYH-1, and occupies #13CH bytes. You must ensure that these 
addresses are free for use after the system is loaded, 


CP/M 2.0 is also easily adapated to disk subsystems whose sector 
size is a multiple of 128 bytes. Information is orovided by the BDOS 
on sector write operations which eliminates the need for pre-read 
operations, thus allowing plocking and deblocking to take place at the 
BIOS level. 


See the "CP/M 2.0 Alteration Guide" for additional details 
concerning tailoring your CP/M system to your varticular hardware, 
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1. INTRODUCTION 


Tne standard CP/M system assumes operation on an Intel MDS-386¢ 
microcomputer development system, but is designed so that the user can 
alter a specific set of subroutines which define the hardware 
operating environment. In this way, the user can produce a diskette 
whicn operates with any IBM-3741 format compatible drive controller 
and other peripheral devices. 


Altnough standard CP/M 2.0 is configured for single density floppy 
disks, field-alteration features allow adaptation to a wide variety of 
disk subsystems from single drive minidisks through high-capacity 
“nard aisk" systems. In order to simplify tne following adaptation 
process, we assume that CP/M 2.0 will first be configured for single 
density floppy disks where minimal editing and debugging tools are 
available, If an earlier version of CP/M is available, the 
customizing process is eased considerably. In this latter case, you 
may wisn to briefly review the system generation process, and skip to 
later sections which discuss system alteration for non-standard disk 
systems, 


In order to achieve device independence, CP/M 1S separated into 
tnree distinct modules: 


BIOS - pasic I/O system which is environment dependent 

BDOS - daSic disk operating system which is not dependent 
upon the hardware configuration 

CCP =- the console command processor which uses the BDOS 


Of these modules, only the BIOS is dependent upon the particular 
nardware, That is, the user can “patch” the distribution version of 
CP/M to provide a new BIOS which provides a customized interface 
between the remaining CP/M modules and the user's own hardware system, 
The purpose of this document is to provide a step-by-step procedure 
for patching your new BIOS into CP/M. 


If CP/M is being tailored to your computer system for the first 


time, the new BIOS requires some relatively simole software 
development and testing. The standard BIOS is listed in Appendix B, 
and can be used as a model for the customized package. A skeletal 


version of the BIOS is given in Avpendix C which can serve as the 
basis for a modified BIOS. In addition to the BIOS, the user must 
write a simple memory loader, called GETSYS, whicn brings’ the 
operating system into memory. In order to patcn the new sBIOS_ into 
CP/M, the user must write tne reverse of GETSYS, called PUTSYS, which 
olaces an altered version of CP/M back onto the diskette. PUTSYS can 
be derived from GETSYS by changing the disk read commands into disk 
write commands. Sample skeletal GETSYS and PUTSYS programs are 
describeaq in Section 3, and listed in Apvendix D. In order to make 
the CP/it4 system work automatically, the user must also supply a cold 
Start loader, similar to the one provided with CP/M (listed in 
Appendices A and B). A skeletal form of a cold start loader is given 
in Appendix E which can serve as a model for your loader, 
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2. FIRST LEVEL SYSTEM REGENERATION 


The procedure to follow to patcn the CP/M system is given below in 
several steps. Address references in each step are shown with a 
following "H“ which denotes the hexadecimal radix, and are given fora Wy 
20K CP/M system. For larger CP/M systems, adda “bias"“ to each 
address whicn is shown with a "+b" following it, wnere b 1s equal to 
tne memory size - 20K. Values for b in various standard memory sizes 


ale 
24K: b = 24K - 20K = 4K = 100048 
S2Ke D = 32K - 20K = 12K = 30008 
4dK: b = 40K —- 20K = 20K = 5000H 
48K: b = 48K -— 20K = 28K = 7600H 
5 OK : Db = 56K —- 20K = 36K = 9OO0H 
62K: Db = 62K -— 20K = 42K = A&O0H 
O4Kks: b = 64K - 20K = 44K = BIOUA 


Note: The standard distribution version of CP/M is set for 
operation within a 28K memory system. Therefore, you must first bring 
up the 26K CP/M system, and then configure it for your actual memory 
Size (see Second Level System Generation). 


(1) Review Section 4 and write a GETSYS program which reads’ the 
first two tracks of a diskette into memory. The data from the diskette 
must begin at location 338H. Code GETSYS so that it starts at 
location 1@¥H (pase of the TPA), as shown in the first ovart of 
Appendix d. 


(2) Test tne GETSYS program by reading a blank diskette into | 
Memory, and check to see that the data has been read properly, and ~ 
that the diskette has not been altered in any way by the GETSYS 
program. 


(3) Run the GETSYS program using an initialized CP/M diskette to 
see if. GETSYS loads CP/AH starting at 338@H (the operating system 
actually starts 1238 bytes later at 34H). 3 


(4) Review Section 4 and write the PUTSYS program which writes 
memory starting at 338W0H back onto the first two tracks of the 
diskette, The PUTSYS program should be located at 200H, as shown in 
the second part of Appendix D. 


(5) Test the PUTSYS program using a blank uninitialized diskette 
by writing a portion of memory to the first two tracks; clear memory 
and read it back using GETSYS. Test PUTSYS completely, since this 
program will be used to alter CP/M on disk. 


(6) Study Sections 5, 6, and 7, along with the distribution 
version of the BIOS given in Appendix B, and write a simple version 
which performs a similar function for the customized environment. Use 
the program given in Appendix C as a model. Call this new BIOS by the 
name CBIOS (customized BIOS). Implement only the primitive disk 
operations on a single drive, and simvole console input/output 
functions in this phase, 
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(7) Test CBIOS completely to ensure that it properly overforms 
console character I/O and disk reads and writes. Be especially 
careful to ensure that no disk write operations occur accidently 
during read operations, and check that the voroper track and sectors 
are addressed on all reads and writes. Failure to make these checks 
may cause destruction of the initialized CP/M system after it is 


patched. 


(8) Referring to Figure 1 in Section 5, note that the B10S is 
placed between locations 4A00H and 4FFFH. Read the CP/M system using 
GETSYS and replace the BIOS segment by the new CBIOS developed in step 
(6) and tested in step (7). ‘This replacement is done in the memory of 
the machine, and will be olaced on the diskette in the next step. 


(9) Use PUTSYS to olace the patched memory image of CP/M onto the 
first two tracks of a blank diskette for testing. 

(10) Use GETSYS to bring the copied memory image from the test 
diskette back into memory at 3380H, and check to ensure that it has 
loaded back properly (clear memory, if possible, before the load). 
Upon successful load, brancn to the cold start code at location 4A0Q0H. 
The cold start routine will initialize vage zero, then jumo to the CCP 
at location 340¥WH which will call the BDOS, which will call the CBIOS. 
The CBIOS will be asked by the CCP to read sixteen sectors on track 2, 
and 1f successful, CP/M will type "A>", the system prompt. 


When you make it tnis far, you are almost on the air. If you have 
trouble, use whatever debug facilities you have available to trace and 
Oreakpoint your CBIOS. 


(11) Upon completion of step (19), CP/M has promoted the console 
for a command input. Test the disk write operation by typing 


SAVE 1 X.COM 
(recall that all commands must be followed by a carriage return). 
CP/M should respond with another prompt (after several disk accesses): 
A> 
If it does not, debug your disk write functions and retry. 
(l2) Then test the directory command by typing 
DIR 
CP/M should respond wita 
As &X COM 
(13) Test the erase command by typing 


BRA X,COM 
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CP/M should respond with the A promot. When you make it this far, you 
snould have an operational system which will only require a_ bootstrap 
loader to function completely. 


(14) Write a pootstrap loader which is similar to GETSYS, and 
place it on track #, sector 1 using PUTSYS (again uSing the test 
diskette, not the distribution diskette). See Sections 5 and 3 for 
more information on the pootstrap operation, 


(15) Retest the new test diskette with the bootstrap loader 
installed by executing steps (11), (12), and (13). Unon completion of 
these tests, type a control-C (control and C keys simultaneously). Tne 
system should then execute a "warm start" which reboots the system, 
and types the A promot. 


(16) At this point, you probably have a good version of your 
customized CP/M system on your test diskette. Use GETSYS to load CP/ 
from your test diskette. Remove the test diskette, place the 
distribution diskette (or a legal copy) into the drive, and use PUTSYS 
to replace the distribution version by your customized version, DO 
not make this replacement if you are unsure of your patch since this 
step destroys the system which was sent to you from Digital Research, 


(17) Load your modified CP/M system and test it by tyving 
DIR 
CP/“4 should resoond with a list of files which are provided on the 
initialized diskette. One such file should be the memory image for 
the debugger, called DDT.COM. 
NOTE: from now on, it is important that you always reboot tne CP/M 
system (ctl-C is sufficient) when the diskette is removed and replaced 


by another diskette, unless the new diskette is to be reaa only. 


(1s) Load and test the debugger by typing 


DDT 
(see the document "CP/M Dynamic Debugging Tool (DDT)" for operating 
orocedures, You should take tne time to become familiar with DDT, it 


will be your pest friend in later steps, 


(19) B8efore making further CBIOS modifications, practice uSing 
the editor (see tne ED user's guide), and assembler (see the ASM 
user's guide). ‘hen recode and test the GETSYS, PUTSYS, and CBIOS 
programs uSing ED, ASM, and DDI. Code and test a COPY program whicn 
does a sector-to-sector copy from one diskette to another to obtain 
back-up copies of the original diskette (NOTE: read your CP/M 
Licensing Agreement; it specifies your legal responsibilities when 
copying the CP/M system). Place the copyright notice 


Copyright (c), 1979 
Digital Research 
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on eacn copy which is made witn your COPY program. 


(20) Modify your CBIOS to include the extra functions for 
ouncnes, readers, sSignon messages, and so-forth, and add the 
facilities for a aaditional disk drives, if desired. You can make 
these changes with the GETSYS and PUTSYS programs which you _ have 
developed, or you can refer to the following section, which outlines 
CPp/M facilities which will aid you in the regeneration process. 


You now have a good copy of the customized CP/M system. Note that 
although the CBIOS portion of CP/M which you have develoved belongs to 
you, the modified version of CP/M which you nave created can be copied 
for your use only (again, read your Licensing Agreement), and cannot 
be legally copied for anyone else's uSe. 


It should be noted that your system remains file-compatible with all 
other CP/M systems, (assuming media compatiblity, of course) which 
allows transfer of non-proprietary software between users of CP/M. 
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3. SECOND LEVEL SYSTEM GENERATION 


Now that you have the CP/M system running, you will want to 
configure CP/M for your memory size. In general, you will first get a ' 
memory image of CP/M with the “MOVCPM" program (system relocator) and “/” 
olace tnis memory image into a named aisk file. The disk file can then 
be loaded, examined, patched, and replaced using the debugger, and 
system generation orogram. For further details on the operation of 
these programs, see the “Guide to CP/M Features and Facilities" 
manual, 


Your CBIOS and BOOT can be modified using ED, and assembled using 
ASM, producing files called CBIOS.HEX and B00T.HEX, which contain the 
macnine code for CBIOS and BOOT in Intel hex format. 


To get the memory image of CP/M into the TPA configured for the 
desired memory size, give the command: 


MOVCPM xx * 


where "xx" is the memory size in decimal K bytes (e.g., 32 for 32K). 
The response will pe: 


CONSTRUCTING xxK CP/M VERS 2.0 
READY FOR "“SYSGEN" OR 
“SAVE 34 CPMxx, COM" 


At this point, an image of a CP/M in the TPA configured for the 
requested memory size. The memory image is at location #99W¥H through a 
227FH. (1.e., The BOOT is at J98HWH, the CCP is at 98@H, the BDOS 
starts at 1130H, and the BIOS is at 1F8@0H.) Note that the memory 
image nas the standard MDS-800 BIOS and BOOT on it. It 1S now 
necessary to save the memory image ina file so that you can patch 

your CBIOS and CBOOT into it: 


SAVE 34 CPMxx.,COM 


The memory image created by the "MOVCPM" program is offset by a 
negative bias so that it loads into the free area of the TPA, and thus 
does not interfere with the operation of CP/M in higher memory. This 
memory image can be subsequently loaded under DDI and examined or 
changed in preparation for a new generation of the system, DDT is 
loaded with the memory image by typing: 


DDT CPMxx.COM Load DDT, then read the CPM 
image 


DDT should respond with 
NEXT PC 
2300 9180 
~ (The DDT promot) 


You can then use the display and disassembly commands to examine 
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portions of the memory image between YAH and 227FH. Note, however, 
that to find any particular address within the memory image, you must 
apply the negative bias to the CP/M address to find the actual 
address. ‘Track #0, sector #1 is loaded to location 996H (you should 
find the cold start loader at 9080H to Y97FH), track #8, sector #2 is 
loaded into 98@H (this is the base of the CCP), and so-forth througn 
the entire CP/M system load. Ina 20K system, for example, the CCP 
resides at the CP/M address 3400H, but is placed into memory at 98@H 
by the SYSGEN program. Thus, the negative bias, denoted by n, 
satisfies 


3400H + n = 980H, or n = 98BHH - 3400H 


Assuming two's complement arithmetic, n = D58@H, which can be’ checked 
by 


3400H + D580H = 160980H = O@98HH (ignoring high-order 
overflow). 


Note that for larger systems, n satisfies 
(3460H+b) + n = 98G6H, Or 
n = 980H - (3400H + b), or 

n = D580H - b. 


The value of n for common CP/M systems is given below 


memory size bias b negative offset n 
20K WOWOH D580H - W88YH = D530H 
24K 19004 D580H 1909H = C5e8WvH 
32K 3000H D580H 3609H = A58WH 
AMOK 5000H D584 5000H = 385830H 
48K 7000H D580H 7900H = 6580H 
5 6K 99 OWH D53WH 9JOOH = 45801 
62K A8@0H D580H A80vH = 2D80H 
64K BO OOH D58GH BOZGH = 25805H 


Assume, for example, 


Hx,n 


and DDT will respond with the value of x+n (Sum) 


First type 


Hexadecimal sum and difference 


that you want to locate the address x within the 
memory image loaded under DDT ina 20K system. 


ana x-n (difference). 


The first number printed by DDT will be the actual memory address in 
The input 


the image where the data or code will be found, 


H3400,D589 


for example, will voroduce 980H as the sum, which is where the CCP is 
located in the memory image under DDT. 


Use the L command to disassemble portions the BIOS located at 
(4AW0H+b) —-n which, when you use the H command, produces an actual 
ra address of 1F8#H. The disassembly command would thus be 
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ee 


L1F8¢ 
It is now necessary to vatch in your CBOOT and CBIOS routines. fhe 
BOOT resides at location §@90@#H in the memory image, If the actual 
load address is “n"“, then to calculate the bias (m) use the command: 


H900,n Subtract load address from 
target address. 


The second number typed in response to the command is the desired Dias 
(m). for example, if your BOOT executes at W9380H, the command: 


H900,80 
will reply 
0980 0889 Sum and difference in hex, 


Therefore, the bias “m“ would be ¥08848H. To read-in the BOOT, give the 
command: 


ICBOOT. HEX Input file CBOOT. HEX 
Then: 
Rm Read CBOOT with a bias of 
m (=90dH—-n) 


You may now examine your CBOOT with: 
LOGY 


We are now ready to replace the CBIOS. Examine the area at I1F8@H 
where the original version of the CBIOS resides, Then type 


ICBIOS. HEX Reaay the “hex" file for loading 


assume that your CBIOS is being integrated into a 20K CP/M system, and 
thus is origined at location 4A%¥H. In order to properly locate the 
CBIOS in the memory image under DDT, we must apply the negative bias n 
for a 20K system when loading the hex file. This is accomolished by 
typing 


RD58d Read the file with bias D53806H 


Upon completion of the read, re-examine the area where the CBIOS has 
been loaded (use an "“LIF8#@" command), to ensure that is was loaded 
properly. When you are satisfied that the change has been made, 
return from DDT using a control-C or “G@" command, 


Now use SYSGEN to replace the patched memory image back onto a 


diskette (use a test diskette until you are sure of your patch), as 
shown in the following interaction 
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SYSGEN Start the SYSGEN program 
SYSGEN VERSION 2.90 Sign-on message from SYSGEN 
SOURCE DRIVE NAME (OR RETURN TO SKIP) 
Respond with a carriage return 
to skip the CP/M read operation 
Since the system is already in 
memory. 
DESTINATION DRIVE NAME (OR RETURN TO REBOOT) 
Respond with "B" to write the 
new system to the diskette in 
drive B. 
DESTINATION ON B, THEN TYPE RETURN 
Place a scratch diskette in 
drive B, then type return. 
FUNCTION COMPLETE 
DESTINATION DRIVE NAME (OR RETURN TO REBOOT) 


Place the scratch diskette in your drive A, and then perform a 
coldstart to bring up the new CP/M system you have configured, 


Test the new CP/M system, and place the Digital Research copyright 
notice on the diskette, as specified in your Licensing Agreement: 


Copyright (c), 1979 
Digital Research 


sad... eee 
4, SAMPLE GETSYS AND PUTSYS PROGRAMS 
Tne following program provides a framework for the GETSYS and 
PUTSYS programs referenced in Section 2. The READSEC and WRITESEC 
Subroutines must be inserted by the user to read and write the 


specific sectors, ed 


GETSYS PROGRAM - READ TRACKS @ AND 1 TO MEMORY AT 338WH 


; REGISTER USE 
; A (SCRATCH REGISTER) 
; B TRACK COUNT (8, 1) 
; C SECTOR? COUNT Pity 2y.2 &s.¢2 6) 
: DE (SCRATCH REGISTER PAIR) 
: HL LOAD ADDRESS 
; SP SET TO STACK ADDRESS 
START: LXI SP,338@H ;SET STACK POINTER TO SCRATCH AREA 
LXI H, 3380H >SET BASE LOAD ADDRESS 
MVI B, ® sSTART WITH TRACK @ 
RDT RK: sREAD NEXT TRACK (INITIALLY 3) 
A aes Ge ;READ STARTING WITH SECTOR 1 
RDSEC: s>READ NEXT SECTOR 
CALL READSEC > USER-SUPPLIED SUBROUTINE 
Eki. yi ;MOVE LOAD ADDRESS TO NEXT 1/2 PAGE 
DAD =D ;HL = HL + 128 
INR C ;SECTOR = SECTOR + 1 
MOV A,C ;CHECK FOR END OF TRACK 
CPI 2/7 
JG RDSEC ;CARRY GENERATED IF SECTOR < 27 
; ARRIVE HERE AT END OF TRACK, MOVE TO NEXT RACK 
INR 8B 
MOV A,B ;TEST FOR LAST TRACK 
Cel 2 
JG RDTRK ;CARRY GENERATED IF TRACK < 2 


ARRIVE HERE AT END OF LOAD, HALT FOR NOW 
HOUT 


=e 606 


USER-SUPPLIED SUBROUTINE TO READ THE OISK 

READSEC: 

ENTER WITH TRACK NUMBER IN RE&GISTER B, 
SECTOR NUMBER IN REGISTER C, AND 
ADDRESS TO FILL IN HL 


mo ae =e 


me ze te TO 


PUSH B ;SAVE B AND C REGISTERS 
PUSH re ;SAVE HL REGISTERS 


perform disk read at this point, branch to 


label START if an error occurs 


POP Hi ;RECOVER HL 

POP B ;RECOVER B AND C REGISTERS 
RET ;BACK TO MAIN PROGRAM 

END START 
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Note that this program is assembled and listed in Appendix C for 
reference purposes, with an assumed origin of 1J9H. The hexadecimal 
operation codes wnich are listed on the left may be useful if the 
program has to be entered through your machine's front panel switcnes. 


The PUTSYS program can be constructed from GETSYS by changing only 
a few operations in the GETSYS program given above, as shown in 
Appendix 0D. The register pair HL become the dump address (next 
address to write), and operations upon these registers do not change 
within the program. The READSEC subroutine is replaced by a WRITESEC 
Subroutine which performs the opposite function: data from address HL 
1S written to the track given by register 8B and sector given py 
register C, It is often useful to combine GETSYS and PUTSYS into a 
Single program during the test and development phase, as shown in the 
Appendix. 
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5. DISKETTE ORGANIZATION 


The sector allocation for the standard distribution version of 
CP/M is given here for reference purposes, The first sector (see 
table on the following page) contains an optional software boot 
section. Disk controllers are often set uv to bring track #8, sector l 
into memory at a specific location (often location J000H). The 
program in this sector, called BOOT, has the responsibility of 
bringing the remaining sectors into memory starting at location 
3400H+b. If your controller does not have a built-in sector load, you 
can ignore the program in track %, sector 1, and begin the load from 
track J sector 2 to location 349¥H+b, 


As an example, the Intel MDS-88@ hardware cold start loader brings 
track #8, sector 1 into absolute address 3¥00WH. Upon loading this 
sector, control transfers to location 3990H, where the bootstrap 
operation commences by loading the remainder of tracks J, and all of 
track 1 into memory, starting at 34#¥H+tbd,. Tne user should note that 
tnis bootstrap loader is of little use in a non-MDS environment, 
although it is useful to examine it since some of the boot actions 
will nave to be duplicated in your cold start loader, 
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] 
Track# Sector# Page# Memory Address CP/M Module name 
69 Ol (boot address) Cold Start Loader 
c™ Jo J 2 bd 34008H+b CCP 
: 03 3480H+b i‘ 
04 01 3500H+b Y 
r U5 . 358WH+b * 
06 2 3680H+D : 
: U7 . 3680H+b ‘ 
- 08 93 370¥H+b | 
‘ 09 " 378@H+b : 
19 G4 3800H+b i 
‘i 11 3880H+b : 
: 12 05 3908H+b : 
: 13 ‘ 3980H+b ‘i 
: 14 66 3A80H+b : 
15 ‘ 3A80H+b : 
16 37 3B00H+b : 
OW 17 7 3B89H+b CCP 
Jv 138 08 3C0GH+b BDOS 
: 19 : 3C89H+b i 
‘ 20 09 3DG9H+b . 
: 21 3D80H+b : 
. 22 12 3E8@H+b : 
F Z3 i 3£89H+b " 
: 24 11 3F00H+b ‘ 
. Z5 : 3F80H+b 
i 26 12 4000H+b ‘i 
cy 1 G1 ‘i 4080H+b : 
: J2 13 41 00H+b . 
: § 3 418@H+b i 
: 4 14 4290H+b ‘ 
: 05 Fe 4280H+b . 
‘ 06 15 430dH+b ‘ 
3 Q7 : 4388H+b ‘ 
‘ 08 16 4490H+b ‘ 
: 09 ‘ 448GH+b : 
, 1d 17 45@9H+b : 
: 11 : 4580H+b sy 
12 18 460GH+b . 
‘ 13 ‘ 4680H+b : 
P 14 19 470@H+b ‘ 
‘ i ‘ 478@0H+b : 
16 20 4808H+b i 
: 7 ‘ 4880H+b 
0 18 24 4966H+b 
G1 19 7 498@H+b BDOS 
a1 20 22 4A6@H+b BIOS | 
fF 22 4A88H+b ‘ 
‘ 23 a3 4B8@H+b : 
y 24 : 4B8@H+b 
: Zo 24 4C@@H+b . 
01 26 " 4C8G@H+b BIOS 
02-76 01-26 (directory and data) 
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6. THE BIOS ENTRY POINTS 


The entry points into the BIOS from the cold start loader and BDOS 
are detailed below. Entry to the BIOS is through a “jump vector" 
located at 4AW9H+b, as shown below (see Apvendices B and C, as well). WY 
The jump vector is a sequence of 17 jumo instructions which’ send 
program control to the individual BIOS subroutines. The BIOS 
Subroutines may be emoty for certain functions (i.e., they may contain 
a Single RET operation) during regeneration of CP/M, but the entries 
must be present in the jump vector, 


The jump vector at 4AW9H+b takes the form shown below, where the 
individual jump addresses are given to the left: 


4A00H+b JMP BOOT 
4A03d+0 JHMP WBOOT 
4AW6H+b JMP CONST 
4A09H+b JMP CONIN 
4A9CHt+D JMP CONOUT 
4A9FH+b) JMP LIST 
4A12H+b JMP PUNCH 
4A15H+b JMP READER 
4A18H+b JMP HOME 
4A1B8d+5 JHP SELDSK 


ARRIVE HERE FROM COLD START LOAD 
ARRIVE HERE FOR WARM START 

CHECK FOR CONSOLE CHAR READY 

READ CONSOLE CHARACTER IN 

WRITE CONSOLE CHARACTER OUT 
WRITE LISTING CHARACTER OUT 

WRITE CHARACTER TO PUNCH DEVICE 
READ READER DEVICE 

MOVE TO TRACK J@ ON SELECTED DISK 
SELECT DISK DRIVE 


4A1LEH+0 JMP SETTRK SET ‘TRACK NUMBER 
4A21H+0 JMP SETSEC SET SECTOR NUMBER 
4A24H+bp JMP SETDMA SET DMA ADDRESS 
4A27d0+b JMP READ READ SELECTED SECTOR 


4AZAH+0 JMP WRITE 
4A2DH+b IMP bi Slot 
4A30H+b JMP StCTRAN 


WRITE SELECTED SECTOR 
RETURN LIST STATUS L J 
SECTOR TRANSLATE SUBROUTINE 


me 60 76 BOG 76 VO BRO ZO WE WH WE WE WE WS WE WE WES 


Each jumo address corresponds to a particular subroutine which 
performs the specific function, as outlined below. There are three 
major divisions in the jump table: the system (re)initialization 
which results from calls on BOOT and WBOOT, simple character I/0 
pertormed by calls on CONST, CONIN, CONOUT, LIST, PUNCH, READER, and 
LISTST, and diskette I/O verformed by calls on HOME, SELDSK, SETTRK, 
SETSEC, SETDMA, READ, WRITE, and SECTRAN, 


All simple character I/O operations are assumed to be performed in 
ASCII, upper and lower case, with high order (parity bit) set to zero, 
An end-of-file condition for an input device is given py an ASCII 
control-z (1AH). Peripheral devices are seen by CP/M as "logical" 
devices, and are assigned to physical devices within the BIOS. 


In order to operate, the BDOS needs only the CONST, CONIN, and 
CONOUT subroutines (LIST, PUNCH, and READER may be used by PIP, but 
not the BDOS). Further, the LISTST entry is used currently only by 
DESPOOL, and thus, the initial version of CBIOS may have empty 
Subroutines for the remaining ASCII devices. 
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Tne characteristics of each device are 


CONSOLE The principal interactive console which communicates 
with the operator, accessed through CONST, CONIN, and 
CONOUT. Typically, the CONSOLE is a device such as a 
CRT or Teletype. 


em 


LIST The principal listing device, if it exists on your 
system, which is usually a hard-copy device, such as a 
printer or Teletype, 


PUNCH The principal tape punching device, if it exists, which 
is normally a high-speed paper tape punch or Teletype. 


READER The principal tape reading device, such as a_e simple 
optical reader or Teletype. 


Note that a single peripheral can be assigned as 
the LIST, PUNCH, and READER device simultaneously. If 
no peripheral device is assigned as the LIST, PUNCH, or 
READER device, the CBIOS created by the user may give 
an appropriate error message so that the system does 
not "hang" if the device is accessed by PIP or _ some 
other user ovrogram, Alternately, the PUNCH and LIST 
routines can just simpoly return, and the READER routine 
can return with a 1AH (ctl-Z) in reg A to _ indicate 
immediate end-of-file, 


implement the “IOBYTE" function which allows 
reassignment of ohysical and logical devices. The 
IOBYTE function createS a mapping of logical to 
physical devices which can be altered during CP/M 
processing (see the STAT commanc). The definition of 
the IOBYTE function corresponds to the Intel standard 
as follows: a single location in memory (currently 
location #§@093H) is maintained, called IOBYTE, which 
defines the logical to physical device mapping which is 
in effect at a particular time, The mapping 1S 
performed by splitting the IOBYTE into four distinct 
fields of two bits each, called the CONSOLE, READER, 
PUNCH, and LIST fields, as shown below: 


most significant least significant 


IOBYTE AT 9803H | LIST | PUNCH | READER | CONSOLE | 


bits 657 mite .42;5° pbite2,3 bits 7,1 


The value in each field can be in the range J6-3, 
defining the assigned source or destination of each 
logical device, The values which can be assigned to 
each field are given below 


(All Information Contained Herein is Proprietary to Digital Research.) 


| 
For added flexibility, the user can ontionally 
| 
| 
| 
| 
| 
15 | 





CONSOLE field (bits 6,1) 


06 - console is assigned to the console printer device (TTY:) 
1 - console is assigned to the CRT device (CRI:) 
2 - batch mode: use the READER as the CONSOLE input, 
and the LIST device as the CONSOLE output (BAT:) 
3 - user defined console device (UCI1:) 
READER inet (bits 253) 


Bi 
) READER is the Teletype device (TTY:) 

1 - READER is the high-speed reader device (RDR:) 
2 - user defined reader # 1 (URI1:) 

3 - user defined reader # 2 (UR2:) 


PUNCH field (bits 4,5) 
0 - PUNCH is the Teletype device (TTY:) 
1 - PUNCH is the high speed punch device (PUN:) 
2 - user defined puncn # 1 (UPI1:) 
3 - user defined vuncn # 2 (UP2:) 


LIST field (bits 6,7) 
®@ - LIST is the Teletype device (TTY:) 
l - LIST 1s the CRT device (CRT:) 
2 - LIST 1s the line printer device (LPT:) 
3 - user defined list device (ULI1:) 


Note again that the imolementation of the IOBYTE is 
optional, and affects only the organization of your 
CBIOS. No CP/M systems use the IOBYTE (althougn they 
tolerate the existence of the I0BYTE at location 
YW¥3H), except for PIP which allows access to the 


physical devices, and STAT whicn allows 
logical-physical assignments to be made and/or 
displayed (for more information, see the "CP/M Features 
and Facilities Guide"). In any case, the IOBYTE 


implementation should be omitted until your basic CBIOS 
is fully implemented and tested; then add the IOBYTE to 
increase your facilities, 


Disk I/O is always performed through a sequence of 
calls on the various disk access subroutines which set 
up the disk number to access, the track and sector ona 
particular disk, and the direct memory access (DMA) 
address involved in the I/O operation, After all these 
parameters nave been set up, a call is made to the READ 
Or WRITE function to perform the actual I/O operation. 
Note that there is often a single call to SELDSK to 
select a disk drive, followed by a number of read or 
write operations to the selected disk before selecting 
another drive for subsequent operations, Similarly, 
there may be a single call to set the DMA address, 
tollowed by several calls which read or write from the 
selectea DMA address before the DMA address is changed, 
The track and sector subroutines are always called 
before the READ or WRITE operations are performed, 
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Note that the READ and WRITE routines’ should 


perform several retries (18 1s standard) before | 
reporting the error condition to the BDOS. If the | 
error condition is returned to the BDOS, it will report | 


the error to the user, The HOME subroutine may or may | 
not actually perform the track @@ Seek, depending upon | 
your controller characteristics; the important point is 

that track 68 has been selected for the next operation, | 
and is often treated in exactly the same manner as | 
SETTRK with a parameter of 9@. 


The exact responsibilites of eacn entry point 
Subroutine are given below: | 


BOOT The BOOT entry point gets control from the cold start 
loader and is’ responsible for basic system 
initialization, including sending a _ signon message 
(which can be omitted in the first version). If the | 
IOBYTE function is implemented, it must be set at this | 
point. The various system parameters which are set py | 
the WBOOT entry point must be initialized, and control 
1s transferred to the CCP at 346@H+b for further 
processing. Note that reg C must be set to zero to 
select drive A. 


WBOOT The WBOOT entry point gets control when a warm start 
occurs. A warm start 1s performed whenever a user 
program branches to location @900H, or when the CPU is 

los reset from the front panel. The CP/M system must be 
loaded from the first two tracks of drive A up to, but 
not including, the BIOS (or CBIOS, if you have 
completed your patch). System parameters must be ini- 


tialized as shown below: 


location 9,1,2 set to JMP WBOOT for warm starts | 
(Q@0G0H: JMP 4A03H+b) 

location 3 set initial value of IOBYTE, if 
implemented in your CBIOS 

location 5,6,7 set to JMP BDOS, which is_ the 
primary entry point to CP/M for 
transient programs, (@9@5H: JMP 
3C@6H+b) | 





(see Section 9 for complete details of page zero use) 
Upon completion of the initialization, the WBOOT 
program must branch to the CCP at 34W0H+b to (re)start 
the system. Upon entry to the CCP, register C is set 
to the drive to select after system initialization. 


CONST Sample the status of the currently assigned console 
device and return @OFFH in register A if a character is 
ready to read, and 9#@H in register A if no console 
characters are ready. 


rn CONIN Read the next console character into register A, and 
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— ——————— —————— 


CONOUT 


LIST 


PUNCH 


READER 


HOME 


SELDSK 


set the parity pit (high order bit) to zero. If no 
console character is ready, wait until a character is 
tyeed vefore returning, 


Send the character from register C to the console 
Output device, The character is in ASCII, with high 
Order parity bit set to zero, You may want to include 
a time-out on a line feed or carriage return, if your 
console device requires some time interval at the end 
of the line (such as a TI Silent 7@@ terminal). You 
can, if you wish, filter out control characters which 
cause your console device to react in a Strange way (a 
control-z causes the Lear Seigler terminal to clear 
tne screen, for examvle). 


Send the character from register C to the currently 
assigned listing device, The character is in ASCII 
with zero parity. 


Send the character from register C to the currently 
assigned punch device, The character is in ASCII with 
zero parity. 


Read the next character from the currently assigned 
reader device into register A with zero parity (high 
Order bit must be zero), an end of file condition is 
reported by returning an ASCII control-z (1AH). 


Return the disk head of the currently selected disk 
(initially disk A) to the track #@@ position. If your 
controller allows access to the track © flag from the 
drive, step the head until the track 6 flag is 
detected, If your controller does not support this 
feature, you can translate the HOME call into a call 
On SETTRK with a parameter of Q@, 


Select the disk drive given by register C for further 
operations, where register C contains @ for drive A, 1 
for drive B, and so-forth up to 15 for drive P (the 
Standard CP/M distribution version supports four 
drives). On each disk select, SELDSK must return in 
Hl the base address of a 16-byte area, called the Disk 
Parameter Header, described in the Section 10. For 
Standard floppy disk drives, the contents of the 
header and associated tables does not change, and thus 
the program segment included in the sample CBIOS 
performs this operation automatically. If there is an 
attempt to select a non-existent drive, SELDSK returns 
HL=8000H as an error indicator. Although SELDSK must 
return the header address on each call, it is 
advisable to postpone the actual physical disk select 
operation until an I/O function (seek, read or write) 
is actually performed, since disk selects often occur 
without utimately performing any disk I/0, and many 
controllers will unload the head of the current disk 
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before selecting the new drive. This would cause an 
excessive amount of noise and disk wear. 


f~ SETTRK Register BC contains the track number for subsedquent 
| disk accesseS on the currently selected drive. You 
can choose to seek the selected track at this time, or 
delay the seek until the next read or write actually 
occurs, Register BC can take on values in the range 
J-76 corresponding to valid track numbers for standard 
floppy disk drives, and §-65535 for non-standard disk 
subsystems, 


SETSEC Register BC contains the sector number (1 through 26) 
for subseguent disk accesses on the currently selected 
drive. You can choose to send this information to the 
controller at this point, or instead delay sector 
selection until a read or write operation occurs, 


SETDMA Register BC contains the DMA (disk memory access) 
address for subsequent read or write operations, For 
example, if B = 09H and C = 89H when SETDMA is called, 
then all subsequent read operations read their data 
into ®8@H through @4FFH, and all subsequent write 
operations get their data from svH through @FFH, until 
the next call to SETDMA occurs. The initial DMA 
address is assumed to be. 38dH. Note that the 
controller need not actually support airect memory | 
access, If, for example, all data is received and 

aN sent through I/O ports, the CBIOS which you construct 
will use the 128 byte area starting at the selected 
DMA address for the memory buffer during the following 
read or write overations, | 


READ Assuming the drive has been selected, the track has 
been set, the sector has been set, and the DMA aaadaress 
has been specified, the READ subroutine attempts to 
read one sector based upon these parameters, and 
returns the following error codes in register A: 


7) no errors occurred 
ll non-recoverable error condition occurred 


Currently, CP/M responds only to a zero or non-zero 
value as the return code, That is, if the value in 
register A is @ then CP/M assumes that the disk 
operation completed properly. If an error occurs, 
however, the CBIOS should attempt at least 18 retries 
to see if the error is recoverable, When an error is 
reported the BDOS will print the message “BDOS ERR ON 
X: BAD SECTOR". The operator then has tne option of | 
typing <cr>°{6, ignore "the error, or cti=C 10 abort, 











WRITE Write the data from the currently selected DMA address 
to the currently selected drive, track, and_ sector, 
tc” The data should be marked as “non deleted data” to 
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ee a RA Ae ee Rene Te eee ON ee 


LIsTst 


SECTRAN 


maintain compatibility with other CP/M systems, The 
error codes given in the READ command are returned in 
register A, with error recovery attemots as described 
above, 


Return the ready status of the list device. Used by 
tne DESPOOL program to improve console response during 
its operation, The value #J§ is returned in A if the 
list device is not ready to accept a character, and 
OFFH if a character can be sent to the printer. Note 
that a @%@ value always suffices, 


Performs sector logical to physical sector translation 
in order to improve the overall response of CP/M. 
Standard CP/M systems are shioved with a “skew factor" 
of 6, where six physical sectors are skipped between 
each logical reaa operation, This skew factor allows 
enough time between sectors for most programs to loaa 
their buffers witnout missing the next sector. In 
particular computer systems which use fast processors, 
memory, and disk subsystems, the skew factor may be 
changed to imvorove overall response. Note, however, 
that you should maintain a single density IBM 
compatible version of CP/M for information transfer 
into and out of your computer system, using ae skew 
factor of 6. In general, SECTRAN receives a logical 
sector number in BC, and a translate table address in 


DE. The sector number is used as an index into the 
translate table, with the resulting pnysical sector 
number in HL, For standard systems, the taoles and 


indexing code is vrovided in the CBIOS and need not be 
changed, 
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7. A SAMPLE BIOS 


fhe program shown in Appendix C can serve as a basis for your 
first BIOS. The simolest functions are assumed in this BIOS, so that 
you can enter it through the front panel, if absolutely necessary. 
Note that the user must alter and insert code into the subroutines for 
CONST, CONIN, CONOUT, READ, WRITE, and WAITIO subroutines, Storage is 
reserved for user-supplied code in these regions, The scratch area 
reserved in page zero (see Section 9) for the BIOS is used in this 
program, so that it could be implemented in ROM, if desired. 


Once operational, this skeletal version can be enhanced to. print 
the initial sign-on message and pertorm better error recovery. The 
Subroutines for LIST, PUNCH, and READER can be filled-out, and the 
IOBYTE function can be imolemented, 
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8. A SAMPLE COLD START LOADER 


The program shown in Appendix D can serve as a basis for your cold 
Start loader. The disk read function must be supplied by the user, 
ana the program must be loaded somehow starting at location 6000. 
Note that svace is reserved for your patch so that the total amount of 
storage required for the cold start loader is 128 bytes, Eventually, 
you will probably want to get this loader onto the first disk sector 
(track wu, sector 1), and cause your controller to load it into memory 
automatically upon system start-uvo. Alternatively, you may wish to 
place tne cold start loader into ROM, and place it above the CP/M 
system, In this case, it will be necesSary to originate the program 
at a hnigner address, and key-in a jump instruction at system start-up 
wnicn orancnes to the loader. Subsequent warm starts will not require 
tnis key-in operation, since the entry point ‘WBOOT’ gets control, 
thus bringing the system in from disk automatically. Note also that 
the skeletal cold start loader has minimal error recovery, which may 
pe enhanced on later versions, 
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9, RESERVED LOCATIONS IN PAGE ZERO 


Main memory page zero, between locations @@H and JWFFH, contains 
several segments of code and data which are used during CP/M 
processing. The code and data areas are given below for reference 
purposes, 


Locations Contents 
from to 
GO0G0H - 9602H Contains a jump instruction to the warm start 


entry point at location 4A93H+b. This allows a 
Simple programmed restart (JMP #@0¥H) or manual 
restart from the front vanel. 


0903H 090 3H Contains the Intel standard IOBYTE, which is 
optionally included in the user's CBIOS, as 


described in Section 6, 


0006 4H 


809 4H Current default drive number (W=A,...,15=P). 


0005H 0007H Contains a jump instruction to the sbdDOS,and 
serves two purposes: JHP 9905H provides the 
primary entry point to the BDOS, as described in 
the manual “CP/M Interface Guide," and LHLD 
@YUV6H brings the address field of the 
instruction to the HL register pair. This value 
is the lowest aadress in memory used by CP/M 
(assuming the CCP iS being overlayed). Note 
that the DDT program will change the address 
field to reflect the reduced memory size in 
debug mode, 


0003dH - O827H (interrupt locations 1 through 5 not used) 


O6030H - 90375 (interrupt location 6, not currently used - 
reserved) 


0Y938H - O@M3AH Restart 7 - Contains a jump instruction into the 
DDT or SID program when running in debug mode 
for programmed breakpoints, but is not otherwise 
used by CP/M. 


Q9YJ3BH - WO3FH (not currently used - reserved) 

WW40H - WO4AFH 16 byte area reserved for scratch by CBIOS, but 
is not used for any purpose in the distribution 
version of CP/M 

00950H - YU5BH (not currently used - reserved) 

W05CH - YOT7CH default file control block produced for a 
transient program by the Console Command 


ProceSSOr, 


067DH. 


Q07FH Optional default random record position 
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0080H - WOOFFH default 1238 byte disk buffer (also filled with 
the command line wnen a_e transient is loaded 
under the CCP). 


Note that this information is set-up for normal operation under 
the CP/M system, but can be overwritten by a transient orogram if the 
BDOS tacilities are not required by the transient, 


If, for example, a particular program performs only simple I/O and 
must begin execution at location ¥, it can be first loaded into the 
TPA, using normal CP/M facilities, witn a small memory move program 
which gets control wnen loaded (the memory move program must get 
control from location @1W#H, which is the assumed beginning of ail 
transient programs). The move program can then proceed to move the 
entire memory image down to location @, ana pass control to the 
starting address ot the memory loaa, Note -that- if the “*8foS is 
overwritten, or if location § (containing the warm start entry voint) 
1S overwritten, then the programmer must bring the CP/M system back 
into memory with a cold start sequence, 


(All Intormation Contained Herein is Proprietary to Digital Research, ) 


z24 


WZ 


18. DISK PARAMETER TABLES, 


Tables are included in the BIOS which describe the particular 
characteristics of the disk subsystem used with CP/M. These tables 
can be either hand-coded, as shown in the sample CBIOS in Appendix C, 
Or automatically generated using the DISKDEF macro library, as shown 
in Appendix B. The purpose here is to describe the elements of these 
tables, 


In general, each disk drive has an associated (16-byte) disk 
parameter header which both contains information about the disk drive 
and provides a scratchpad area for certain BDOS operations, The 
format of the disk parameter header for each drive is shown below 


Disk Parameter Header 
| XLT | 9008 | 86800 | 0680 |DIRBUF| DPB | cSV | ALV | 
16b 16b 16b 16b 16b 16b 16b 16b 


where each element is a word (16-bit) value. The meaning of each Disk 
Parameter Header (DPH) element is 


XLT Address of the logical to physical translation vector, 
if used for this particular drive, or the value Q000H 
if no sector translation takes place (i.e, the physical 
and logical sector numbers are the same). Disk drives 
with identical sector skew factors share the same 
translate tables, 


GB00 Scratchpad values for use within the BDOS (initial 
value iS unimportant). 

DIRBUF Address of a 128 byte scratchpad area for directory 
operations within BDOS. All DPH's address the same 


scratchpad area, 


DPB Address of a disk parameter block for this drive. 
Drives with identical disk characteristics address the 
same disk parameter block. 


CSV Address of a scratchpad area used for software check 
for changed disks, This address is different for each 
DPH. 

ALV Address of a scratchpad area used by the BDOS to keep 


disk storage allocation information. This address is 
different for each DPH, 


Given n disk drives, the DPH's are arranged in a table whose first row 


of 16 bytes corresponds to drive 8, with the last row corresponding to 
drive n-l. The table thus appears as 


(All Information Contained Herein is Proprietary to Digital Research.) 


25 





DPBASE: 


90 |XLT 60| 6900 | 6900 | 9O9B |DIRBUFIDBP OBBICSV BOIALV GB 


$1 |XLT @01| 0009 | 80008 | 9900 |DIRBUF|IDBP @1|CSV BZ1LIALV @1| 


n-1|XLTn-1| 6609 | 08008 | 6908 |DIRBUF|DBPn-1|CSVn-1|ALVn-1 | 
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where the label DPBASE defines the base address of the DPH table, 


A responsibility of the SELDSK subroutine is to return the base 
address of the DPH for the selected drive. The following sequence of 
operations returns the table address, with a @@@0H returned if the 
selected drive does not exist, 


NDISKS EQU 4 *NUMBER OF DISK DRIVES 
SELDSK: 
*>SELECT DISK GIVEN BY BC 
LAL H,@@O009H +:ERROR CODE 
MOV A,C *DRIVE OK? 
CPI NDISKS CY IF SO 
RNC *RET IF ERROR 
*NO ERROR, CONTINUE 
MOV by ° LOW (DISK) 
MOV H,B *HIGH (DISK) 
DAD H 2 *2 
DAD H 2 *4 
DAD H 2 *8 
DAD H °*16 
LXI D,DPBASE :FIRST DPH 
DAD D *DPH (DISK) 
RET 


The translation vectors (XLT @@ through XLTn-1) are located 
elsewhere in the BIOS, and_ simply correspond one-for-one with the 
logical sector numbers zero through the sector count-l. The Disk 
Parameter Block (DPB) for each drive is more complex. A particular 
DPB, which is addressed by one or more DPH's, takes the general form 


16b 8b 8b 8b 16b 16b 8b 8b 16b 16b 


where each is a byte or word value, as shown by the "8b" or “16b" 
indicator below the field. 


SPT is the total number of sectors per track 
BSH is the data allocation block shift factor, determined 
by the data block allocation size, 
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EXM is the extent mask, determined by the data block 
aliocation size and the number of disk blocks. 


DSM determines the total storage capacity of the disk drive 


DRM determines the total number of directory entries which 
can be stored on this drive AL@,AL1 determine reserved 
directory blocks, 


CKS is the size of the directory check vector 


OFF is the number of reserved tracks at the beginning of 
the (logical) disk. 


The values of BSH and BLM determine (implicitly) the data allocation 
Size BLS, which is not an entry in the disk parameter block. Given 
that the designer has selected a value for BLS, the values of BSH and 
BLM are shown in the table below 


BLS BSH BLM 
1,024 3 7 
2,948 4 15 
4,096 5 ca 
Ojo 2 6 63 

16,384 7 127 


where all values are in decimal. The value of EXM depends upon both 
the BLS and whether the DSM value is less than 256 or greater than 
255, as Shown in the following table 


BLS DSM < 256 DSM > 255 
1,024 i) N/A 
2,048 1 4) 
4,096 2 1 
8,192 7 3 

16,384 15 7 


The value of DSM is the maximum data block number supported by 
this particular drive, measured in BLS units. The product BLS times 
(DSM+1) is the total number of bytes held by the drive and, of course, 
must be within the capacity of the physical disk, not counting the 
reserved operating system tracks. 


The DRM entry is the one less than the total number of directory 
entries, which can take on a 16-bit value, The values of AL@ and ALI, 
however, are determined by DRM, The two values AL@® and AL1 can 
together be considered a string of 16-bits, as shown below. 
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92 01 O92 03 04 05 806 O7 G8 09 18 111213 14 15 


where position @@ corresponds to the high order bit of the byte 
labelled AL#@, and 15 corresponds to the low order bit of the byte 
labelled AL1. Each bit position reserves a data block for number of 
directory entries, thus allowing a total of 16 data blocks to be 
assigned for directory entries (bits are assigned starting at @@ and 
filled to the right until position 15). Each directory entry occupies 
32 bytes, resulting in the following table 


BLS Directory Entries 
1,024 32 times # bits 
2,048 64 times # bits 
4,096 128 times # bits 
8,192 256 times # bits 

16,384 512 times # bits 


Thus, if DRM = 127 (128 directory entries), and BLS = 1024, then there 
are 32 directory entries per block, requiring 4 reserved blocks. In 
this case, the 4 high order bits of AL® are set, resulting in the 
values AL® = @FOH and AL] = OOH. 


The CKS value is determined as follows: if the disk drive media 
is removable, then CKS = (DRM+l1)/4, where DRM is the last directory 
entry number, If the media is fixed, then set CKS = @ (no directory 
records are checked in this case), 


Finally, the OFF field determines the number of tracks which are 
skipped at the beginning of the physical disk. This value is 
automatically added whenever SETTRK is called, and can be used as a 
mechanism for skipping reserved operating system tracks, or _ for 
partitioning a large disk into smaller segmented sections, 


To complete the discussion of the DPB, recall that several DPH'’s 
can address the same DPB if their drive characteristics are identical. 
Further, the DPB can be dynamically changed when a new drive is 
addressed by simply changing the pointer in the DPH since the _ BDOS 
copies the DPB values to a local area whenever the SELDSK function is 
invoked, 


Returning back to the DPH for a particular drive, note that the 
two address values CSV and ALV remain, Both addresses reference an 
area Of uninitialized memory following the BIOS. The areas must _ be 
unigue for each drive, and the size of each area is determined by the 
values in the DPB, 


The size of the area addressed by CSV is CKS bytes, which is 
sufficient to hold the directory check information for this particular 


drive, If CKS = (DRM+1)/4, then you must reserve (DRM+1)/4 bytes for 
directory check use, If CKS = @, then no storage is reserved, 
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The size of the area addressed by ALV is determined by the 
maximum number of data blocks allowed for this particular disk, and is 
computed as (DSM/8)+1. 


The CBIOS shown in Appendix C demonstrates an instance of these 
tables for standard 8" single density drives. It may be useful to 
examine this program, and compare the tabular values with the 
definitions given above, 
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ll. THE DISKDEF MACRO LIBRARY. 


A macro library is shown in Appendix F, called DISKDEF, which 
greatly simplifies the table construction process. You must have 
access to the MAC macro assembler, of course, to use the DISKDEF 
facility, while the macro library is included with all CP/M 2.90 
distribution disks. 


A BIOS disk definition consists of the following sequence of 
macro statements: 


MACLIB DISKDEF 
DISKS n 
DISKDEF @,... 
DISKDEF 1,... 


DISKDEF n-l 


ENDEF 


where the MACLIB statement loads the DISKDEF.LIB file (on the same 
disk as your BIOS) into MAC's internal tables, The DISKS macro call 
follows, which specifies the number of drives to be configured with 
your system, where n iS an integer in the range 1 to 16. A series of 
DISKDEF macro calls then follow which define the characteristics of 
each logical disk, 9@ through n-1l (corresponding to logical drives A 
through P). Note that the DISKS and DISKDEF macros generate the 
in-line fixed data tables described in the previous section, and thus 
must be placed in a non-executable portion of your BIOS, typically 
directly following the BIOS jump vector. 


The remaining portion of your BIOS is defined following the 
DISKDEF macros, with the ENDEF macro call immediately preceding the 
END statement, The ENDEF (End of Diskdef) macro generates’ the 
necessary uninitialized RAM areas which are located in memory above 
your BIOS, 


The form of the DISKDEF macro call is 


DISKDEF dn,fsc,lsc,|[skf],bls,dks,dir,cks,ofs, [9] 


where 
dn 1s the logical disk number, @ to n-l 
fsc is the first physical sector number (@ or 1) 
lsc is the last sector number 
skf is the optional sector skew factor 
bls is the data allocation block size 
dir is the number of directory entries 
cks is the number of “checked" directory entries 
ofs 1s the track offset to logical track @@ 
[8] 1s an optional 1.4 compatibility flag 


The value "dn“ is the drive number being defined with this DISKDEF 
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macro invocation, The "fsc" parameter accounts for differing sector 
numbering systems, and is usually @ or l. The "“lsc" is the last 
numbered sector on a track. When present, the "“skf" parameter defines 
the sector skew factor which is used to create a sector translation 
table according to the skew. If the number of sectors is less’ than 
256, a Single-byte table is created, otherwise each translation table 
element occupies two bytes, No translation table is created if the 


Skf parameter is omitted (or equal to @)., The “bls" parameter 
specifies the number of bytes allocated to each data block, and takes 
on the values 1624, 2648, 4896, 8192, or 16384, Generally, 


performance increases with larger data block sizes since there are 
fewer directory references and logically connected data records are 
physically close on the disk. Further, each directory entry addresses 
more data and the BIOS-resident ram space is reduced, The "dks" 
specifies the total disk size in "bls" units, That is, if the bls = 
2048 and dks = 1606, then the total disk capacity is 2,048,000 bytes, 
If dks is greater than 255, then the block size parameter bls must be 
greater than 1024, The value of "“dir" is the total number of 
directory entries which may exceed 255, if desired, The "“cks" 
parameter determines the number of directory items to check on each 
directory scan, and is used internally to detect changed disks during 
System operation, where an intervening cold or warm start has not 
occurred (when this situation is detected, CP/M automatically marks 
the disk read/only so that data is not subsequently destroyed). As 
Stated in the previous section, the value of cks = dir when the media 
is easily changed, as is the case with a floppy disk subsystem, If 
the disk is permanently mounted, then the value of cks is typically @, 
Since the probability of changing disks without a restart is quite 
low. The “ofs" value determines the number of tracks to skip when 
this particular drive is addressed, which can be used to reserve 
additional operating system space or to simulate several logical 
drives on a single large capacity physical drive, Finally, the [98] 
parameter is included when file compatibility is reguired with 
versions of 1.4 which have been modified for higher density disks. 
This parameter ensures that only 16K is allocated for each directory 
record, aS waS the case for previous’ versions, Normally, this 
parameter is not included, 


For convenience and economy of table space, the special form 
DISKDEF ste 
gives disk i the same characteristics as a previously defined drive j. 


A standard four-drive single density system, which is compatible with 
version 1.4, is defined using the following macro invocations: 
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DISKS 4 
DISKDEF 9,1,26,6,19024,243,64,64,2 
DISKDEF 1 

DISKDEF 2 
DISKDEF 3 


ENDEF 


with all disks having the same parameter values of 26 sectors per 
track (numbered 1 through 26), with 6 sectors skipped between each 
access, 1024 bytes per data block, 243 data blocks for a total of 243k 
byte disk capacity, 64 checked directory entries, and two operating 
system tracks, 


The DISKS macro generates n Disk Parameter Headers (DPH's), 
Starting at the DPH table address DPBASE generated by the macro. Each 
disk header block contains sixteen bytes, as described above, and 
correspond one-for-one to each of the defined drives, In the four 


drive standard system, for example, the DISKS macro generates a table 
of the form: 


DPBASE EQU $§$ 

DPEQ: DW XLT6,000¥H,9000H,0900H,DIRBUF ,DPB29,CSVO,ALVO 
DPE * DW XLTO ,O000H,09000H,0000H,DIRBUF,DPBY,CSV1,ALV1 
DPE2: DW XLTO ,0000H,0000H,0000H,DIRBUF ,DPBY,CSV2,ALV2 
DPE3: DW XLTO ,0000H,®@000H,0000H,DIRBUF,DPBY,CSV3,ALV3 


where the DPH labels are included for reference purposes to show the 
beginning table addresses for each drive @ through 3. The values 
contained within the disk parameter header are described in detail in 
the previous section, The check and allocation vector addresses are 


generated by the ENDEF macro in the ram area following the BIOS code 
and tables, 


Note that if the “skf" (skew factor) parameter is omitted (or 
equal to @), the translation table is omitted, and a @®@@@0H value is 
inserted in the XLT position of the disk parameter header for’ the 
disk. In a subsequent call to perform the logical to physical 
translation, SECTRAN receives a tranSlation table address of DE = 
O0080H, and simply returns the original logical sector from BC in the 
HL register pair. A translate table is constructed when the _ skf 
parameter is present, and the (non-zero) table address is placed into 
the corresponding DPH's. The table shown below, for example, is 
constructed when the standard skew factor skf = 6 is specified in the 
DISKDEF macro call: 


XLT@: DB Le olay 9 25g S5 i Ly ll yp 235s 69 pt Oye 
DB 2,8,14,20,2646,12,18,24,4,10,16;,22 


Following the ENDEF macro call, a number of uninitialized data 
areas are defined. These data areas need not be a part of the BIOS 
which is loaded upon cold start, but must be available between the 
BIOS and the end of memory. The size of the uninitialized RAM area is 
determined by EQU statements generated by the ENDEF macro. For a 
Standard four-drive system, the ENDEF macro might produce 
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4C72 = BEGDAT EQU $ 
(data areas) 
4DB9 = ENDDAT EQU §$ 
G13C = DATSIZ EQU $-BEGDAT 


which indicates that uninitialized RAM begins at location 4C72H, ends 
at 4DB#@H-l1, and occupies @13CH bytes. You must ensure that these 
addresses are free for use after the system is loaded, 


After modification, you can use the STAT program to check your 
drive characteristics, since STAT uses the disk parameter block to 
decode the drive information. The STAT command form 


STAT d:DSK: 


decodes the disk parameter block for drive d (d=A,...,P) and displays 
the values shown below: 


128 Byte Record Capacity 
Kilobyte Drive Capacity 
32 Byte Directory Entries 
Checked Directory Entries 
Records/ Extent 

Records/ Block 

Sectors/ Track 

Reserved Tracks 


rn ODA aA RK 


Three examples of DISKDEF macro invocations are shown below with 
corresponding STAT parameter values (the last produces a Full 
8-megabyte system). 


DISKDEF @,1,58,,2048,256,128,128,2 


r=4996, k=512, d=128, c=128, e=256, b=16, s=58, t=2 


DISKDEF 0,1,58,,2048,1024,300,0,2 
r=16384, k=2048, d=300, c=0, e=128, b=16, s=58, t=2 


DISKDEF 6,1,58,,16384,512,128,128,2 
r=65536, k=8192, d=128, c=128, e=19024, b=128, s=58, t=2 
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12, SECTOR BLOCKING AND DEBLOCKING, 


Upon each call to the BIOS WRITE entry point, the CP/M BDOS 
includes information which allows effective sector blocking and 
deblocking where the host disk subsystem has a sector size which 1S a 
multiple of the basic 128-byte unit. The purpose here is to present a 
general-purpose algorithm which can be included within your BIOS which 
uses the BDOS information to perform the operations automatically. 


Upon each call to WRITE, the BDOS provides the _ following 
information in register C: 


normal sector write 
write to directory sector 
write to the first sector 
of a new data block 


4) 
1 
2 


Condition @ occurs whenever the next write operation is into a 
previously written area, such as a random mode record update, when the 
write is to other than the first sector of an unallocated block, or 
when the write is not into the directory area, Condition 1 occurs 
when a write into the directory area is performed, Condition 2 occurs 
when the first record (only) of a newly allocated data block is 
written, In most cases, application programs read or write multiple 
128 byte sectors in sequence, and thus there is little overhead 
involved in either operation when blocking and deblocking' records 
Since pre-read operations can be avoided when writing records. 


Appendix G lists the blocking and deblocking algorithms in skeletal 
form (this file is included on your CP/M disk). Generally, the 
algorithms map all CP/M sector read operations onto the host disk 
through an intermediate buffer which is the size of the host disk 
sector. Throughout the program, values and variables which relate to 
the CP/M sector involved in a seek operation are prefixed by "sek," 
while those related to the host disk system are prefixed by "hst,." 
The equate statements beginning on line 29 of Appendix G define the 
mapping between CP/M and the host system, and must be changed if other 
than the sample host system is involved. 


The entry points BOOT and WBOOT must contain the initialization 
code starting on line 57, while the SELDSK entry point must be 
augmented by the code starting on line 65. Note that although the 
SELDSK entry point computes and returns the Disk Parameter Header 
address, it does not physically selected the host disk’at this point 
(it is selected later at READHST or WRITEHST). Further, SETTRK, 
SETTRK, and SETDMA simply store the values, but do not take any other 
action at this point, SECTRAN performs a trivial trivial function of 
returning the physical sector number, 


The principal entry points are READ and WRITE, starting on lines 
118 and 125, respectively. These subroutines take the place of your 
previous READ and WRITE operations, 

The actual physical read or write takes place at either WRITEHST 
Or READHST, where all values have been prepared: hstdsk 1s the host 
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disk number, hsttrk is the host track number, and hstsec is the host 
sector number (which may require translation to a physical sector 


number). You must insert code at this point which performs the full 
host sector read or write into, or out of, the buffer at hstbuf of 
length hstsiz. All other mapping functions are performed by the 
algorithms. 


This particular algorithm was tested using an 8@ megabyte hard 
Gisk unit which was originally configured for 128 byte sectors, 
producing approximately 35 megabytes of formatted storage, When 
configured for 512 byte host sectors, usable storage increased to 57 
megabytes, with a corresponding 480% improvement in overall response. 
In this situation, there iS no apparent overhead involved in 
deblocking sectors, with the advantage that user programs still 
maintain the (less memory consuming) 128-byte sectors, This 1s 
primarily due, of course, to the information provided by the BDOS 
which eliminates the necessity for pre-read operations to take place. 
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APPENDIX A: THE MDS COLD START LOADER 


eo =e %*-e 6 


false 
true 


testing 


e 
a 


bias 


bias 


cpmb 
bdos 
bdose 
boot 
rboot 


? 
coldstar 


MDS-8090 Cold Start Loader for CP/M 2.90 


Version 2.8 August, 1979 


equ Q 

equ not false 

equ false 

a: testing 

equ 93400h 

endif 

if not testing 

equ O8Odh 

endif 

equ bias s;base of dos load 
equ 886h+bias sentry to dos for calls 
equ 188@h+bias send of dos load 
equ 160@0h+bias scold start entry point 
equ boott3 swarm start entry point 
org 3000h sloaded here by hardware 
equ bdose-cpmb 

egu 2 stracks to read 

equ bdos1/128 °# sectors in bdos 
equ 25 ># on track 9g 

equ bdoss-bdos@ °# on track 1 

equ ®f800h s;intel monitor base 

equ @ffOfh ;restart location for mon8@ 
equ 78h ;'base’ used by controller 
equ basetl ;result type 

equ base+3 ;result byte 

equ base+7 ;reset controller 

equ base ;disk status port 

equ base+l ;low iopb address 

equ base+2 ;high lopb address 

equ BEEh sboot switch 

equ 3h erecalibrate selected drive 
equ 4h disk read function 

equ 1@0h suse end of boot for stack 
1xi sp,stack;in case of call to mon8@ 
clear disk status 

in rtype 

in rbyte 

check if boot switch is off 

Ss 

in bsw 

onz Ostastart>”* = CO one 
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3610 
3612 


3815 
3016 
3018 
3619 
301b 
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3622 
3024 
3626 


3928 


302b 


302d 
302e 
3631 
3032 


3034 


3037 
303a 
303b 
303c 


303f 


a3/£ 


0662 
214238 


7d 
d379 
7c 
ad37va 
db78 
oo s3¢ 


db79 


e603 
feg2 


d20930 


db7b 


17 
dcOf£fFt 
lf 
eole 


C20030 


1107080 
19 
05 
c21530 


c30616 


oT 


~=e =~ me me 


=e se 06 


=e se 


clear the controller 


out reset elogic cleared 
mvi b,ntrks s:number of tracks to read 
1x1 h,1iopbé 


read first/next track into cpmb 


mov a,l 

out ilow 

mov a,h 

out ihigh 

in dstat 

$2. waitd 

check disk status 

in rtype 

ani lib 

cpl 2 

Lt testing 

cnc rmon8@ ;:g0 to monitor if 11 or 19 
endif 

if not testing 

jJnec rstart ;retry the load 

endif 

in rbyte :i/o complete, check status 
if not ready, then go to mon8@ 

ral 

cc rmon8@ ;not ready bit set 
rac erestore 

ani 11119b ;o0verrun/addr err/seek/crc 
if testing 

Ong. rmon8@ ;go to monitor 

endif 

if not testing 

jnz rstart ;retry the load 

endif 

Le d,iopbl ;length of iopb 

dad d addressing next iopb 
dcr b -count down tracks 
jnz start 


jmp boot, print message, set-up jmps 
jmp boot 


parameter blocks 
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3942 
3043 
3044 
3045 
3046 
3047 
0007 


3049 
304a 
304b 
304c 
304d 
304e 
30528 


10pb0: 


i1opbl 


10pbl: 





80h -10cw, no update 
readf sread function 
bdos@ °# sectors to read trk @ , g 
Q strack @ 
2 ;Start with sector 2, trk @ 
cpmb ;start at base of bdos 
S-10pb@ 
80h 
readf 
bdosl ;sectors to read on track 1] 
1 strack 1] 
] sector 1 
cpmb+bdos@*128 ;:base of second rd 
wy 
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4a0O 
3400 
3c@6 
1600 
@B2c 
GBG2 
GOO4 
0080 
Q@0Va 


c3b34a 
c3c34a 
c3614b 
c3644b 
c36a4b 
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bdos 
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nsects 
offset 
cdisk 
buff 
retry 
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wboote: 


B: THE MDS BASIC I/O SYSTEM (BIOS) 


mds-80@ i/o drivers for cp/m 2.90 
(four drive single density version) 


version 2.@ august, 1979 

equ 20 eversion 2.90 
copyright (c) 1979 

digital research 


box 579, pacific grove 
california, 939590 


org 4a@@h sbase of bios in 20k system 

equ 3490h sbase of com ccnp 

equ 3c06h sbase of bdos in 20k system 

equ S-cpmb ;length (in bytes) of cpm system 
equ cpml1/128:number of sectors to load 

equ 2 snumber of disk tracks used by cp 
equ G004h saddress of last logged disk 

equ GV8VWh default buffer address 

equ 10 smax retries on disk i/o before e 


perform following functions 
boot cold start 
wboot warm start (save i/o byte) 
(boot and wboot are the same for mds) 
const console status 
reg-a = ®@@ 1f no character ready 
reg-a = ff if character ready 
conin console character in (result in reg-a) 
conout console character out (char in reg-c) 
list list out (char in reg-c) 
punch punch out (char in reg-c) 
reader paper tape reader in (result to reg-a) 
home move to track @@ 


(the following calls set-up the io parameter bloc 
mds, which is used to perform subsequent reads an 
seldsk select disk given by reg-c (@,1,2...) 
settrk set track address (@,...76) for sub r/w 
setsec set sector address (1l,...,26) 

setdma set subsequent dma address (initially 80h 


read/write assume previous calls to set i/o parms 
read read track/sector to preset dma address 
write write track/sector from preset dma addres 


jump vector for indiviual routines 


jmp boot 
jmp wboot 
jmp const 
jmp conin 
jmp conout 
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4a@f c36d4b jmp list 
4a12 ¢c3724b jmp punch 
4a15 ¢c3754b jmp reader 
4a18 c3784b jmp home 
4alb c37d4b jmp seldsk 
4ale c3a74b jmp settrk 
4a21 c3ac4b jmp setsec 
4a24 c3bb4b jmp setdma 
4a27 c3cl4b jmp read 
4a2a c3ca4b jmp write 
4a2d c3764b jmp listst ;list status 
4a30@ c3bl1l4b jmp sectran 
maclib diskdef ;load the disk definition library 
disks 4 four disks 
4a33+= dpbase equ S base of disk parameter blocks 
4a33+824aG0 dped: dw x1t@,000Gh stranslate table 
4a37+0000080 dw GBGGh,090Gh escratch area 
4a3b+6e4c73 dw dirbuf,dpbé@ dir buff,parm block 
4a3f+0d4dee dw csv@,alvdé echeck, alloc vectors 
4a43+824a90 dpel: dw x1lt1,0008h etranslate table 
4a47+9 00000 dw G000h,0880GbHh scratch area 
4a4b+6e4c73 dw dirbuf,dpbl s;dir buff,parm block 
4a4f+3c4dld dw csvl,alvl scheck, alloc vectors 
4a53+824a00 dpe2: dw x1t2,@9000h stranslate table 
4a57+0 00009 dw G00G0hH,W@00Gh escratch area 
4a5b+6e4c73 dw dirbuf,dpb2 dir buff,parm block 
4a5f+6b4d4c dw csv2,alv2 check, alloc vectors 
4a63+824a00 dpe3: dw x1t3,0000h stranslate table 
4a67+0 60000 dw G@09GGh, 0ORWHh scratch area 
4a6b+6e4c73 dw dirbuf,dpb3 sdir buff,parm block 
4a6f£+9a4d7b dw csv3,alv3 scheck, alloc vectors 
diskdef 0,1,26,6,1024,243,64,64,offset 
4a73+= dpbd equ S$ *disk parm block 
4a73+1a0@ dw 26 ;sec per track 
4a75+83 db > sblock shift 
4a76+07 db 7 block mask 
4a7/7/+0@ db 4) -extnt mask 
4a78+£200 dw 242 disk size-l 
4a7at+3£00 dw 63 sdirectory max 
4a7ct+cg db 192 sallocd@ 
4a7d+00 db G sallocl 
4a7et+1000 dw 16 check size 
4a86+¥ 200 dw 2 offset 
4a82+= x1tZ equ S) stranslate table 
4a82+61 db ti 
4a8 3+67 ab fi 
4a84+Wd db § Se 
4a85+13 ab 19 
4a86+19 db 25 
4a87+05 db 5 
4a88+Gb db 11 
4a89+11 db 17 
4a8at+17 db 23 
4a8b+9 3 db 3 


4a8c+09 
4a8dt+0Ff 
4a8et+15 
4a8£+92 
4a90+08 
4a91+@e 
4a92+14 
4a93+la 
4a94+06 
4a95+dc 
4a96+12 
4a97+18 
4a98+64 
4a99+Va 
4a9atl1@ 
4a9b+16 


4a/3+= 
GG1lf+= 
Q010+= 
4a82+= 


4a/3+= 
OO1lE+= 
OG10+= 
4a82+= 


4a/3+= 
O01f+= 
9019+= 
4a82+= 


@dfd 
O@fc 
OOF3 
OW7e 


£800 
f£fOf 
£803 
£806 
£809 
£8G0c 
£8Of 
£812 


dpbl 
alsl 
cssl 
pay ws 


dpb2 
als2 
css2 
x1lt2 


dpb3 
als3 
css3 
x1t3 


ba i i CL) 


revrt 


intc 
icon 
inte 


g 


mons@ 
rmon8gg@ 


cl 
ri 
co 
po 
lo 
csts 


diskdef 
equ 
equ 
equ 
equ 
diskdef 
equ 
equ 
equ 
equ 
diskdef 
equ 
equ 
equ 
equ 


endef occurs at 


;egquivalent parameters 

ssame allocation vector size 
ssame checksum vector size 
*same translate table 


;egquivalent parameters 

ssame allocation vector size 
ssame checksum vector size 
ssame translate table 


;equivalent parameters 

;same allocation vector size 
esame checksum vector size 
ssame translate table 

end of assembly 


end of controller - independent code, the remaini 
are tailored to the particular operating environm 
be altered for any system which differs from the 


the following code assumes the mds monitor exists 
and uses the i/o subroutines within the monitor 


we also assume the mds system has four disk drive 


equ 
equ 
equ 
equ 


@fdh 
Ofch 
8f3h 


;interrupt revert port 
sinterrupt mask port 
;interrupt control port 


®111$111@b;enable rst O@(warm boot),rst 7 


mds monitor equates 


equ 
equ 
equ 
equ 
equ 
equ 
equ 
equ 


Of£800h 
Off0fh 
®£803h 
®£806h 
Of£809h 
O£80ch 
Of£80fh 
Of£812h 
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emds monitor 

;restart mon8@ (boot error) 
;console character to reg-a 
sreader in to reg-a 

sconsole char from c to console o 
;punch char from c to punch devic 
slist from c to list device 
;console status @0/ff to register 











9078 
9078 
0079 
687b 


G079 
OBila 


GQO4 
0006 
6003 
OBG4 
GB0d 
GGVa 


4a9c 
4a9f 
4aal 
4aad 
4ap@ 


4ab3 
4ab6 
4ab9 
4abc 
4abd 
4ac@ 


4ac3 


4ac6 
4ac8 


4ac9 
4acc 
4acf 
4adl 
4ad4 
4ad6 
4ad9 
4adb 


4ade 
4adf 


OGd@ava 
3230 


6b2043£ 


322e30 
Q9dvadB 


316001 


328400 
c30f4b 


318080 


Veda 
cS 


910034 
cdbb4b 
Ged 
cd7d4b 
Gedo 
cda74b 
Geg2 
cdac4b 


cl 
G62c 


Ssignon: 


? 
boot: 


wboooté: 


=e 6 


disk ports and commands 


equ 78h ;base of disk command io ports 
equ base -disk status (input) 

equ basetl ;result type (input) 

equ base+3 ;result byte (input) 

equ baset+tl ;iopb low address (output) 
equ base+2 ;iopb high address (output) 
equ 4h sread function 

equ 6h swrite function 

equ 3h erecalibrate drive 

equ 4h ;1i1/fo finished mask 

equ @dh ;Carriage return 

equ Qah sline feed 


;Signon message: xxk cp/m vers y.y 
db og aren ere a 


"20° ;sample memory size 


ab "k cp/m vers ' 
db vers/10+'@','.',vers mod 1@+'g' 
db cr,lf,9 


;print signon message and go to ccp 
(note: mds boot initialized iobyte at @@G@3h) 


1xi sp,buff+8@h 

1xi h,signon 

call prmsg sprint message 

xra a *clear accumulator 

sta cdisk ;set initially to disk a 
jmp gocpm 7;go to cp/m 


loader on track @, sector 1, which will be skippe 
read cp/m from disk - assuming there is a 128 byt 
start, 


1lxi sp,buff ;using dma —- thus 88 thru ff ok f 
mvi c,retry ;max retries 

push b 

senter here on error retries 

ixi b,cpmb ;set dma address to start of disk 
call setdma 

mv c,Q s;boot from drive @ 

call seldsk 

mvi c,@ 

call settrk ;start with track @ 

mv c,2 ;Start reading sector 2 

call setsec 


count nsects to zero 
°l@-error count 


read sectors, 


pop b 
mMvi b,nsects 
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fela 
dag54b 


3a6a4c 
3c 


c2el4a 


£3 
3e12 
d3fd 
af 
d3fc 
3e7e 
d3fc 
af 
d3f£3 


G18909 
cdbb4b 


3ec3 

320008 
21034a 
220100 
320506 
21863c 
220600 
323800 
2160£8 
223900 


rasec: 


rdl: 


=e i(Q se we 
Oo 
=) 


=e we 


=e 6 


=e 


eread next sector 


push 
call 
jnz 
lhlid 
1x1 
dad 
mov 
mov 
call 
lda 
cpl 
ake 


must be 


lda 
inr 
mov 
call 
xra 
inr 
mov 
call 
pop 
Ger 
jnz 


done with the load, 


b 
read 


*save sector count 


booterr ;retry if errors occur 


1od 
qd,128 
d 

b,h 
Spd 
setdma 
10S 

26 

rdl 
sector 
1ot 

a 

Cum 
settrk 
a 

a 

C,a 
setsec 
b 

b 
rdsec 


*increment dma address 
*sector size 
*incremented dma address in hl 


sready for call to set dma 


ssector number just read 
sread last sector? 


26, zero and go to next track 
get track to register a 


sready for call 
eclear sector number 
*to next sector 


sready for call 


srecall sector count 
done? 


*(enter here from cold start boot) 
enable rst@ and rst7 


di 

mvi 
out 
XxLra 
out 
mvi 
out 
Xxra 
out 


a,1l2h 
revrt 
a 

Lnte 
a,inte 
intc 

a 

icon 


*initialize command 


cleared 
erst® and rst/7 bits on 


sinterrupt control 


set default buffer address to 8@h 


1x1 
call 


b, buff 
setdma 


reset monitor entry points 


mvi1 
sta 
1x1 
shid 
sta 
1xi 
shlid 
sta 
1xi 
shld 


a, jmp 
") 


h,wboote 


7*8+1 


:Jmp wbhoot at location 90 


-jmp bdos at location 5 


;jmo to mon8@ (may have been chan 


leave iobyte set 
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reset default buffer address 





4b41 
4b44 
4b45 
4b46 


4b49 
4b4a 
4b4b 


4b4e 
4b4f 


4b52 
4655 
4658 


4b5b 


4bol 


4b64 


4b67 


4b69 


4b6a 


4b6d 


4b70 
4b71 


4b72 


4b75 


3a 400 
4f 
fb 
c39034 


cl 
0d 
ca524b 


cS 
c3c94a 


215b4b 
cdd34b 
c30fff 


3£626f4 


c312f8 


cd@3f8 


e67f 


c9 


c309£8 


c30ff8 


af 
c9 


c38cf8 


c366f8 


=e 


oO ~e =e 


me 


booter@: 


v 


bootmsg: 


conin: 


a 
conout: 


list: 


a 


punch: 


o 
a 


7 
reader: 


home: 


ooterr: 


previously selected disk was b, send varameter to 


lda cdisk slast logged disk number | 
mov cC,a -send to ccp to log it in a 
el 
jmp cpmb 
error condition occurred, print message and retry 
pop b srecall counts 
dcr Cc 
Jz booterg@ 
try again 
push b 
mp wbooté 
otherwise too many retries 
1xi h,bootmsg 
call prmsg 
jmp rmon8@ ;mds hardware monitor 
db '?boot’ ,@ 
sconsole status to reg-a 
(exactly the same as mds call) 
jmp csts } 
sconsole character to reg-a 
cali Gl 
ani 7£h sremove parity bit 
ret 
console character from c to console out 
jmp co 
slist device out 
(exactly the same as mds call) 
mo lo 
s;return list status 
xra a 
ret salways not ready 
punch device out 
(exactly the same as mds call) 
jmp po 
*reader character in to reg-a 
(exactly the same as mds call) 
jmp ri 
WT 


smove to home position 
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=e 


treat as track @@ seek 


HeWD mvi c,@ 
c3a74b jmp settrk 
seldsk: ;select disk given by register c 
210000 1xi h,@@00h sreturn @008 if error 
719 MOV a,c 
feg4 cpl ndisks ;too large? 
ag rnc eleave hl = 8000 
e602 ani 1éb 708 ®@ for drive @,1 and 18 18 fo 
32664c sta dbank sto select drive bank 
79 mov a,c 700, 01, 10, 11 
e601 ani lb smds has @,1l at 78, 2,3 at 88 
b7 ora a eresult @@? 
ca924b JZ setdrive 
3e30 mvi a,@G11808Bb -selects drive 1 in bank 
setdrive: 
47 mov b,a ssave the function 
21684c 1x1 h,iof ‘io function 
7e mov a,m 
e6ocf ani 11001111b smask out disk number 
b@ ora b mask in new disk number 
77 mov m,a ssave 1t in l1opb 
8200 ROY AG shl=disk number 
29 dad h e *2 
29 dad h kA 
29 dad h 2 *8 
29 dad h 2*16 
11334a 1x1 d,dpbase 
19 dad d ehl=disk header table address 
c9 ret 
settrk: ;set track address given by c 
216a4c 1x1 h,iot 
FB mov m,c 
c9 ret 
setsec: ;set sector number given by c 
216b4c 1xi h,1ios 
71 mov m,c 
ey ret 
sectran: 
stranslate sector bc using table at de 
0600 mv b,@ ;double precision sector number i 
eb xchg stranslate table address to hl 
G9 dad b stranslate(sector) address 
Je mov a,m *translated sector number to a 
326b4c sta 10s 
6§ mQ l,a sreturn sector number in 1 


setdma: 


-set dma address given by regs b,c 
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I 
ee 





226c4c 
c9 


GeV4 
cde 4b 
cdf£04b 
c9 


c3d34b 


21684c 


Qeda 


ca3f4c 
cd4c4c 


3a664c 


rite: 


Sse sxe 


’ 
’ 
0 
prmsg: 


v 
setfunc: 


° 
g 


v 
waitio: 


rewait: 


=e 


mov 1 gt 
Mov gee 
shlid 10d we 
ret 
sread next disk record (assuming disk/trk/sec/dma 
mvi c,readf ;set to read function 
call setfunc 
call waitio ;perform read function 
ret smay have error set in reg-a 
disk write function 
mvi c,writf 
call setfunc ;set to write function 
call waitio 
ret smay have error set 
utility subroutines 
sprint message at h,l to @ 
MOV a,m 
ora a 7zero? 
rz 
more to print 
push h 
Mov C,a 
call conout | 
inx h 
jmp prmsg 
set function for next i/o (command in reg-c) 
1xi h,iof io function address 
Mov a,m sget it to accumulator for maskin 
ani 1111100@b sremove previous command 
ora Cc sset to new command 
MOV m,a sreplaced in iopb 
the mds-88@ controller req's disk bank bit in sec 
mask the bit from the current i/o function 
ani G@Z1GGHBOb emask the disk select bit 
i Rea} h,ios saddress the sector selec 
ora m s;select proper disk bank 
mov m,a eset disk select bit on/o 
ret 
mvi c,retry ;max retries before perm error 
Start the i/o function and wait for completion 
call intype ;in rtype 
call inbyte ;clears the controller 

WwW 
lda dbank eset bank flags 
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4bfb 
Abfc 
4bfe 
4c00 
4c@3 
4c@5 
4cé6 
4c08 


4céb 
4céd 
4cide 


4cl®@ 
4cl13 
4cl5 


4c18 


4clb 
4cld 


4c2¢ 
4c21 


4c24 
4c27 
4c28 
4c2b 
4c2c 
4c2e 


4¢c31 


4c32 
4c35 


b7 
3e67 
G64c 
c20b4c 
d379 
78 
d37a 
c3194c 


e604 
cal®4c 


cd3f4c 


fe@2 
ca324c 


b7 
c2384c 


eofe 
c2384c 


c9 


cd4c4c 
c3384c 


=e BO 


wready: 


7 
Werror: 


=e %O6 SO WO VE WE WOH WE WO WO 


ora a szero if drive 9,1 and nz 
mvi a,iopb and @ffh ;low address for iovb 

mvi b,iopb shr 8 shigh address for iopb 
jnz iodrl sdrive bank 1? 

out llow slow address to controlle 
mov a,b 

out ihigh shigh address 

jmp waitd sto wait for complete 
drive bank 1] 

out ilow+1@h 88 for drive bank 1@ 

mov a,b 

out ihigh+16h 

call instat swalt for completion 

anl lordy ;ready? 

jz waitd 

check io completion ok 

call intype smust be io complete (06) 
0% unlinked i/o complete, 91 linked i/o comple 
1@ disk status changed 11 (not used) 

cpl 1b ;ready status change? 

Iz wready 

must be @8 in the accumulator 

ora a 

jnz werror -some other condition, re 


check i/o error bits 


call 
ral 
4¢ 
rar 
ani 
jnz 


inbyte 

wready sunit not ready 
11111116b sany other errors? 
werror 


read or write is ok, accumulator contains zero 


ret 


snot ready, treat as error for now 


call 
jmp 


ereturn hardware malfunction (crc, 


inbyte ;Clear result byte 


trycount 


track, seek, e 


the mds controller has returned a bit in each pos 
of the accumulator, corresponding to the conditio 


4) 


SO mB WD EF 


- deleted data (accepted as ok above) 

- cre error 

- seek error 

- address error (hardware malfunction) 

- data over/under flow (hardware malfunct 
- write protect (treated as not ready) 

- write error (hardware malfunction) 

- not ready 
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a te emcee FO 


4c38 
4¢c39 


4c3c 
4c3e 


4c3f 
4c42 
4c43 
4c46 
4c48 
4c49 
4c4b 


4c4c 
4c4f 
4c50 
ACS3 
4¢c55 
4c56 
4c58 


4c59 
4c5c 
4c5d 
4c6@ 
4c62 
4c63 
4c65 


4c66 


4c67 
4c68 
4c69 
4c6oa 
4c6b 
4c6oc 


Od 
c2£24b 


=e ct me "=O @O BW WOH WO 


=e we 


~ 


intypl: 


inbyte: 


inbytl: 


instat: 


instal: 


dbank: 


1opb: 


ntypes: 


(accumulator bits are numbered 7654321 @Q) 


it may be useful to filter out the various condit 
but we will get a permanent error message if it i 
recoverable, in any case, the not ready conditio 
treated as a separate condition for later improve 


rycount: 


register c contains retry count, decrement ‘til z 
GCE Cc 
jnz rewait ;for another try 


cannot recover from error 


mvi a,l error code 

ret 

intype, inbyte, instat read drive bank 98 or 19 
lda dbank 

ora a 

jnz intypl ;skip to bank 198 
in rtype 

ret 

in rtypet+l@h 78° fer Y,1 68. LOL 2,3 
ret 

lda dbank 

ora a 

jnz inbytl 

in rbyte 

ret 

in rbytet+l1@h 

ret 

lda dbank 

ora a 

jnz instal 

in dstat 

ret 

in dstat+l1@h 

ret 


data areas (must be in ram) 


db Q disk bank @@ if drive @,1l 
° 1@ if drive 2,3 

710 parameter block 

db 80h snormal i/o operation 

db readf °-10 function, initial read 

db 1 snumber of sectors to read 

db offset ;track number 

db 1 *sector number 

dw buff °10 address 


define ram areas for bdos operation 
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Cy 4c6et= begdat equ S$ 
4c6et Girbuf: ds 128 edirectory access buffer 

4ceet alv®@: ds 31 
4d@d+ csv@: ds 16 
4dldt alvl: ds 31 
4d3ct csvl: ds 16 
4d4c+ alv2: ds 31 
4d6bt+ cSsv2: ds 16 
4d7b+ alv3: ds 31 
4d9at csv3: ds 16 
4daat= enddat equ $ 
G13ct= Gatsiz equ $-begdat 





GOBH 
3400 
3c@6 
4a@Q 
GOG4 
0003 


4a@Q 
Q@2c 


4ad@ 
4a@3 
4a¥6 
4a@9 
4auc 
4avf 
4al2 
4al5 
4al18 
4alb 
4ale 
4a21 
4a24 
4a27 
4a2a 
4a2d 
4a3@ 


4a33 
4a37 
4a3b 
4a3f 


4a43 
4a47 
4a4b 
4a4f 


4a53 
4a57 
4a5b 
4a5f 


c39c4a 
c3a64a 
c3114b 
c3244b 
c3374b 
c3494b 
c34d4b 
c34f4b 
c3544b 
c35a4b 
c37d4b 
c3924b 
c3ad4b 
c3c34b 
c3d64b 
c34b4b 
c3a74b 


734a0@ 
GOKOD 
£04c8d 
ec4d7@ 


734a00 
QOOGOO 
£84c8d 
fc4d8Ft 


734a0O 
GOGO 
£04c8d 
Gc4eae 


size 


~e me ™O ~O 3 me ~e 


bias 
ccp 
bdos 
bios 
cdisk 
1obyte 


v 


nsects 


e 
f 


2 
0 


wboote: 


pbase: 


APPENDIX 


C: A SKELETAL CBIOS 


skeletal cbios for first level of cp/m 2.@ altera 


equ 


“bias” is address offset from 340@h for memory sy 
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;cp/m version memory size in kilo 


than 16k (referred to as “b" throughout the text) 


equ 
equ 
equ 
equ 
equ 
equ 


org 
equ 


(msize-20) *1024 
340@h+bias 
ccp+896h 
ccp+16da0h 


9004h 
0083h 


bios 


sbase of ccp 


base of bdos 

sbase of bios 

scurrent disk number @=a,...,15=p 
sintel i/o byte 


Origin of this program 
(S-ccp) /128 


swarm start sector count 


Jump vector for individual subroutines 


jmp 
jmp 
jmp 
jmp 
jmp 
jmp 
jmp 
mp 
jmp 
jmp 
jmp 
jmp 
jmp 
jmp 
jmp 
jmp 
J™Mp 


boot 
wboot 
const 
conin 
conout 
list 
punch 
reader 
home 
seldsk 
settrk 
setsec 
setdma 
read 
write 
listst 


sectran 


;cold start 

swarm start 

console status 
sconsole character in 
econsole character out 
elist character out 
spunch character out 
*reader character out 
smove head to home positi 
*select disk 

sset track number 

sset sector number 
*set dma address 

sread disk 

ewrite disk 

ereturn list status 
ssector translate 


fixed data tables for four-drive standard 


ibm-compatible 8" disks 


disk parameter header for disk @@ 


dw 
dw 
dw 
dw 


trans,09@00h 
G000h,9900h 
dirbf,dpblk 
chk#@@,a1190@ 


disk parameter header for disk 61 


dw 
dw 
dw 
dw 


trans,@00@h 
G800h,8@00Bh 
dirbf,dpblk 
chk#91,al1l1901 


disk parameter header for disk @2 


dw 


trans,09900h 
G9800Gh,9B900h 
dirbf,dpblk 
chk@2,a11902 
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~ 


wo 


4a63 
4a67 
4a6b 
4a6f 


434 4 
4al7b 
4al7f 
4a83 
4a87 
4a8b 


4a8d 
4a8f 
4a9@ 
4a9l 
4a92 
4a94 
4a96 
4a97 
4a98 
4a9a 


734ad@ 
GOGVWID 
£@4c8d 
lc4ecd 


198586 


170369 
159268 
141a96 
121804 
1816 


af 

320300 
320400 
c3ef4a 


318009 
GeO 

cd5a4b 
cd544b 


Q62c 


ged 
1662 


218034 


7 ) 


ct se =e 


rans; 


dpblk: 


oO ~e me ee ~O 


oot: 


wooots: 


=e 


loadl: 


disk parameter header for disk 93 


dw trans,@000h 
dw G90Gh,WVGHh 
dw dirbf,dpblk 
dw chk@3,al11@3 


sector translate vector 


gp ye Betis 17 iseckgrs 1-¢-4-8 

b Lids) yo BEE ceay: oe 164 ll, 12 
db Ai ae 5B 2S sectors 13.1041 Sea 
db 280,26,6,12 ssectors 17,18,19,20 
db 18,24,4,19 sectors 21,22,23,24 
db 16,22 ssectors 25,26 


;disk parameter block, common to all disks 


dw 26 ;sectors per track 
db 3 sblock shift factor 
db 7 block mask 

db Q snull mask 

dw 242 disk size-l 

dw 63 ;directory max 

db 192 salloc @ 

db Gj salloc 1 

dw 16 check size 

aw 2 strack offset 


end of fixed tables 


individual subroutines to perform each function 
esimplest case is to just perform parameter initi 


xra a -;zero in the accum 
sta lobyte -Cclear the iobyte 
sta cdisk ;select disk zero 
jmp gocpm sinitialize and go to cp/ 


simplest case is to read the disk until all sect 


1xi sp,8@h suse space below buffer f 
mvi c,Q sselect disk @ 

call seldsk 

call home 7go to track 00 

mvi b,nsects :b counts # of sectors to 
mvi c,d sc has the current track 
mvi CZ. sd has the next sector to 


note that we begin by reading track @, sector 2 s 
contains the cold start loader, which is skipped 


1xi h,ccp sbase of cp/m (initial lo 
;load one more sector 
push b ssave sector count, current track 
push d save next sector to read 
push h ;save dma address 
mov Ca sget sector address to register c 
call setsec ;set sector address from register 
pop b erecall dma address to b,c 
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4ac2 
4ac3 


4ac6 
4ac9 
4acb 


4ace 
4acf 
4ad2 
4ad3 
4ad4 
4ad5 
4ad6 


4adq9g 
4ada 
4adb 
4add 


4aed 
4ae2 


4ae3 
4ae4 
4ae5 
4ae6 
4ae9 
4aea 
4aeb 
4aec 


4aef 
4afl 
4af4 
4af7 


4afa 
4afd 
4b0@ 


4b@3 
4b06 


4b09 
4béa 
4bdd 
4bde 


c5 
cdad4b 


cdc34b 
fev 
c2a64a 


caef4a 


14 

7a 
felb 
daba4a 


16@1 
Oc 


c3ba4a 


3ec3 

320000 
21034a 
220100 


320500 
21063c 
220660 


G18000 
cdad4b 


fb 
3aV 400 
4f 
c30034 


me ~O 


=e BO 


=e 6 


=e 0 


OO we ~e 
‘@) 
eo 
f= 


=e 


ey 


=e 





sreplace on stack for later recal 
eset dma address from b,c 
track set, sector set, dma addres 


sany errors? 
sretry the entire boot if an erro 


move to next sector 


srecall dma address 

*dma=dmat128 

snew dma address is inh,l 
srecall sector address 

srecall number of sectors remaini 
-sectors=sectors-l 

stransfer to cp/m if all have bee 


more sectors remain to load, check for track chan 


s;sector=27?, if so, change tracks 


scarry generated if sector<27 


end of current track, go to next track 


push b 

call setdma 
drive set to @, 
call read 
cpl 9h 
jnz wboot 
no error, 

pop h 

lxi d,128 
dad d 

pop d 

pop b 

dcr b 

jz gocpm 
inr d 

mov a,d 
cpl 27 

Bi: load] 
mvi d,l 
inr C 


sbegin with first sector of next 
s;track=track+tl 


Save register state, and change tracks 


push 
push 
push 
call 
pop 
pop 
pop 
jmp 


end of load operation, 


mvi 
sta 
1xi 
shld 


sta 
1x1 
shld 


1x1 
call 


ei 
lda 
mov 


jmp 


b 

d 

h 
settrk 
h 

d 

b 
loadl 


a,@c3h 
Q 


h,wboote 


1 


5 
h,bdos 
6 


b,8@h 
setdma 


cdisk 
C,a 
ccp 
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strack address set from register 


*for another sector 
set parameters and go to c 


7c3 1S a Jmp instruction 
;for jmp to wboot 
swboot entry point 
set address field for jmp at @ 


>for jmp to bdos 
sbdos entry point 
saddress field of jump at 5 to bd 


sdefault dma address is 8@h 


;enable the interrupt system 

sget current disk number 

send to the ccp 

7;g0 to cp/m for further processin 


4b11 
4b21 
4b23 


4b24 
4b34 
4b36 


4b37 
4b38 
4b48 


4b49 
4b4a 


4b4b 
4b4c 


4b4d 
4b4e 


4b4f 
4b51 
4b53 


3e00 
c9 


e67£ 
c9 


719 


c9 


79 
c9 


af 
c9 


719 
c9 


3ela 
e67f 
c9 


GedG 
cd7d4b 
c9 


210080 
79 
32ef4c 
feg4 


Q ™~e ™=0@ CTO ~TO ZO WE 


onst: 


jam me 
j- 
¢) 
cr 
ee 


listst: 


punch: 


ry =e ~e 


ome s 


me pa =e se SO TE WO WE 


seldsk: 


eader: 


simple i/o handlers (must be filled in by user) 
in each case, the entry point is provided, with s 
to insert your own code 


console status, return @ffh 1f character ready, 


ds 10h space for status subroutine 
mv1 a,@6h 
ret 


econsole character into register a 


ds 18h Space for input routine 
ani 7£h strip parity bit 
ret 


sconsole character output from register c 


mov a,c get to accumulator 
ds 16h ;space for output routine 
ret 


from register c 
character to register a 
enull subroutine 


list character 
mov a,c 
ret 


sreturn list status (@ if not ready, 1 if ready) 
xra a °-$@ is always ok to return 
ret 


*punch character from register c 
mov a,c character to register a 
ret snull subroutine 


eread character into register a from reader devic 


mvi a,lah enter end of file for now (repla 
ani 7£h sremember to Strip parity bit 
ret 


ifo drivers for the disk follow 
for now, we will simply store the parameters away 
in the read and write subroutines 


smove to the track @@ position of current drive 
translate this call into a settrk call with param 


mvi c,@ eselect track @ 
call settrk 
ret ewe will move to @@ on first read 


;select disk given by register c 


1x1 h,@@@@h s;error return code 

mov a,c 

sta diskno 

cpl 4 s;must be between @ and 3 
53 


dg 


32eb4c 


22ed4c 


c9 


c3e64b 


rnc “no Cangry,2£ 45555 e< 
: disk number is in the proper range 


ds 10 space for disk select 
: compute proper disk parameter header address 
lda diskno 
MOV l,a el=disk number @,1,2,3 
mvi h,@ shigh order zero 
dad h » *2 
dad h 7 *A 
dad h 2 *8 
dad h >*16 (size of each header) 
1x1 d,dpbase 
daa d shl=.dpbase (diskno*l16) 
ret 


settrk: ;set track given by register c 


mMOv a 

sta track 

ds 10h *Space for track select 
ret 


7 
setsec: ;set sector given by register c 


mov a,c 
Sta sector 
ds 18h *space for sector select 
ret 
, 
sectrans: 


translate the sector given by bc using the 
translate table given by de 


xchg shl=.trans 

dad b ehl=.,trans(sector) 
mov 1,m °-l = trans(sector) 
mv1 h,@ ehl= trans(sector) 
ret swith value in hl 


setdma: ;set dma address given by registers b and c 


mMOv L,c slow order address 

Mov hgh shigh order address 

shld dmaad save the address 

ds 16h sspace for setting the dma addres 

ret 
read: sperform read operation (usually this is similar 
: so we will allow space to set up read command, th 
; common code in write) 

ds 1h eset up read command 

jmp waitio ;to perform the actual i/o 
write: ;perform a write operation 

ds 10h sset up write commanu 
waitio: ;enter here from read and write to perform the ac 
; operation. return a @9@h in register a if the ope 
° properly, and @lh if an error occurs during the r 
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in this case, we have saved the disk number in '"d 
the track number in ‘track’ (0-76 
the sector number in ‘sector’ (l- 
the dma address in ‘dmaad’ (9-655 


=e se SO BVO TO 


4be6 ds 256 *space reserved for i/o drivers 
4ce6 3e@1 mvi a,l ;error condition 
4ce8 c9 ret sreplaced when filled-in 


the remainder of the cbios is reserved uninitiali 
data area, and does not need to be a part of the 
system memory image (the space must be available, 
however, between “begdat" and “enddat"). 


e =e VO BVO WO WE 


a 


4ce9 track: ds 2 stwo bytes for expansion 
4ceb sector: ds 2 stwo bytes for expansion 
4ced dmaad: ds 2 *direct memory address 
4cef diskno: ds 1 disk number @-15 
° scratch ram area for bdos use 

4cf@ = begdat egu $ sbeginning of data area 
4cf@ dirbf: ds 128 ;scratch directory area 
4a70 all@@: ds 31 eallocation vector @ 
4d8f all@l: ds 31 sallocation vector l 
4dae all@2: ds 31 sallocation vector 2 
4dcd all@3: ds 31 ;allocation vector 3 
4dec chk@@: ds 16 check vector @ 

O™ 4dfc chk@l: ds 16 scheck vector 1 
4e0c chk@2: ds 16 check vector 2 
4elc chkd3: ds 16 check vector 3 
4e2c = enddat equ $ send of data area 
G@13c = datsiz eau S-begdat;size of data area 


4e2c end 





0190 


9014 


GOO 
3400 
3c0O 
4a00 


0100 
9103 
0106 


$108 


G1da 
010d 
91120 
111 
9112 
6113 
0115 


9118 
9119 
Glla 
Glic 


O11f 
9120 


318033 
218033 
8600 
GeGl 


cd@003 


felb 


feG2 


daé8el 


fb 
76 





APPENDIX D: A SKELETAL GETSYS/PUTSYS PROGRAM 


combined getsys and putsys programs from Sec 4, 


; Start the programs at the base of the TPA 3 
org G100h 

msize equ 20 * size of cp/m in Kbytes 

>; “bias" is the amount to add to addresses for > 29k 

° (referred to as "b" throughout the text) 

bias equ (msize-2@) *1924 

ccp equ 3400h+bias 

bdos equ ccp+@ 808h 

bios equ ccp+1600h 

: getsys programs tracks @ and 1 to memory at 

: 3880h + bias 

; register usage 

: a (scratch register) 

° b track count (@...76) 

: « sector count (1...26) 

; d,e (scratch register pair) 

; hyd load address 

- sp set to stack address 

gstart > start of getsys wy 
1x1 sp,ccp-@8@8@h * convenient plac 
1lxi h,ccp-@980h ; set initial loa 
mvi b,@ > Start with trac 

rdStrk: >; read next track 
mvi Cyl * each track star 

rdsSsec: 
call readSsec >; get the next se 
ip et qd,128 >; offset by one s 
dad d : (hl=h1+128) 
inr Cc > next sector 
mov a,c * fetch sector nu 
cpl 27 : and see if la 
jc rdsec > <, Go one more 

>; arrive here at end of track, move to next track 
inr b - track = track+tl 
mov a,b > check for last 
cpl 2 > track = 2 ? 
jc rdstrk *« <€, do another 

; arrive here at end of load, halt for lack of anything b 
ei 
hlt a 
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0200 


9200 
9203 
9206 


9208 


@20a 
920d 
9219 
9211 
@212 
9213 
9215 


9218 
0219 
92la 
@21c 


O21f 
9220 


9300 


9300 
9301 
9302 


9342 
9343 


3189033 
218933 


8600 
GeGl 


cdagge4 
118009 


19 
Oc 
719 
felb 


daGa¥2 


G4 
78 
feg2 


dag@802 


fb 
76 


c5 
e5 


el 
cl 


=e 26 BO 


org 


putSsys: 
1x1 
1xi 
mvi 

wrStrk: 
mvi 

wrssec: 
call 
1xi 
dad 
inr 
mov 
cpl 
jc 


* arrive here at end of track, move to 


inr 
mov 
cpl 
jc 


me 


el 
hilt 


(S+210@h) and O££0Gh 


sp,ccp-@880h 
h,ccp-9@080h 
b,@ 


Cyd 


writeSsec 
qd,128 


wrssec 


b 

a,b 

2 
wrStrk 


done with putsys, halt for lack 


=e @=6@ WO 


=e 
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putsys program, places memory image starting at 
388dh + bias back to tracks 8 and l 
start this program at the next page boundary 


convenient plac 
Start of dump 
Start with trac 


Start with sect 


write one secto 
length of each 
<hl>=<hl> + 128 
<c> = <a> + 1 
see if 

past end of t 
no, do another 


next track 


=e @=6 BO ZO 


track = track+l 
see if 

last track 
no, do another 


of anything bette 


> user supplied subroutines for sector read and write 


me 


org 


readSsec: 


move to next page boundary 


($+@1900h) and Of£OGh 


=e %O TO BWE 


push b 
push h 
* user defined read operation goes here 
ds 64 
pop h 
pop b 


read the next sector 


track in <b>, 
sector in <c> 
dmaaddr in <hl> 
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6344 
9400 


0400 
9461 
G402 
@442 


0443 
9444 


@445 


c9 


C5 


cl 
c9 


ret 
org ($S+#2190@h) and @£EGOh 
writeSsec: 


+ Same parameters as readssec 


push b 
push h 
> user defined write operation goes here 
ds 64 
pop h 
pop b 
ret 


> end of getsys/putsys program 


end 
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GO00 


0014 


GVWO 
3460 
4a@ad 
9300 
4a0g 
1900 
0032 


9608 B10200 
0603 1632 
9805 210034 
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APPENDIX E: A SKELETAL COLD START LOADER 


this is a sample cold start loader which, when modified 
resides on track @@, sector 91 (the first sector on the 
diskette). we assume that the controller has loaded 
this sector into memory upon system start-up (this pro- 
gram can be keyed-in, or can exist in read/only memory 
beyond the address space of the cp/m version you are 
running). the cold start loader brings the cp/m system 
into memory at “loadp" (34@@h + "“bias"). ina 20k 
memory system, the value of "bias" is §@0@h, with large 
values for increased memory sizes (See section 2). afte 
loading the cp/m system, the clod start loader branches 
to the "boot" entry point of the bios, which begins at 
"bios" + "bias," the cold start loader is not used un- 
til the system is powered up again, as long as the bios 
is not overwritten, the origin is assumed at 900@h, an 
must be changed if the controller brings the cold start 
loader into another area, or if a read/only memory area 
is used, 


org g > base of ram in cp/m 
msize equ 20 ; min mem size in kbytes 
bias egu (msize-20)*1024 ; offset from 20k system 
ccp equ 3400h+bias ; base of the ccp 
bios equ ccp+16a0h >; base of the bios 
biosl equ 6308h * length of the bios 
boot egu bios 
size equ biost+biosl-ccp ; size of cp/m system 
sects equ size/128 > # of sectors to load 


begin the load operation 


1x1 b,2 > b=0, c=sector 2 
mvi d,sects > d=# sectors to load 
1xi Ry, CCD * base transfer address 


lsect: * load the next sector 


insert inline code at this point to 
read one 128 byte sector from the 
track given in register b, sector 
given in register c, 

into the address given by <hl> 


branch to location "cold" if a read error occurs 
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0008 
088b 


G06b 
8G6c 


c36b0G 


15 
caéd4a 


318000 
a2 


davs8ug 


GeGl 
64 
c30800 


KEKKKEKKEKRKEEKKEKEKEKKKEKEKEKKEKRKERRKERKEKKKEKEKRKRKEKKKKRKKKKRKEKREE 
* 
- user supplied read operation goes here... 
* 
KEKKKREKKEEKKERKEKEKRKKEKEKKRKRKKKKRKRKRKRKKKRKRKKRKKRKRKRKRKEESK 
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jmp pastSpatch * remove this when patche 
ds 60h 
pastSpatch: 
; go to next sector if load is incomplete 
dcr d - sects=sects-l 
By boot > head for the bios 
H more sectors to load 
> we aren’t uSing a stack, so use <sp> as scratch registe 
: to hold the load address increment 
1xi sp,128 ; 128 bytes per sector 
dad sp e <hl> = <hl> + 128 
inr Cc * sector = sector + l 
mov a,c 
cpl 27 * last sector of track? 
Jc lsect > no, go read another 


> end of track, increment to next track 


mvi c,l * sector = l] 

incr b * track = track + l 
jmp lsect >; for another group 
end * of boot loader 
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APPENDIX F:., CP/M DISK DEFINITION LIBRARY 


CP/M 2.0 disk re-definition library 


Copyright (c) 1979 
Digital Research 
Box 579 

Pacific Grove, CA 
93950 


CP/M logicel disk drives are defined using the 


macros given below, where the sequence of calls 
1S: 


disks ral 

diskdef oarameter-list-9 
diskdef parameter-list-l 
diskdef parameter-list-n 
endef 


where n is the number of logical disk drives attached 
to the CP/M system, and parameter-list-i defines the 
characteristics of the ith drive (i=#,1,...,n-1l) 


each parameter-list-1i takes the form 
dn,tsc,lsc,[skf],b1s,cks,dir,cks,ofs, [#] 


where 

dn is the disk number @,1,...,n-l 

fsc is tie first sector number (usually 2% or 1) 
lsc is tae last sector number on a track 

Skf is optional “skew factor” for sector translate 
bls is tne data block size (1024,2048,...,16384) 
dks is tne disk size in bls increments (word) 

dir is tne number of directory elements (word) 

cks is tne number of dir elements to checksum 

ofs is the number of tracks to skip (word) 

[G] is an optional 9 which forces 16K/directory en 


for convenience, the form 

dn,dm 
defines disk dn as having the same characteristics as 
a previously defined disk dm, 


a standard four drive CP/M system is defined by 


disks 4 

diskder 0,1,26,6,1924,243,64,64,2 
dsk set Q 

rept 3 
dsk set dsk+l 

diskdef %dsk,@ 

endm 

endec 


the value of “begdat" at the end of assembly defines t 
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OQinw~e O,s0e se se Se we we we NO 


disks 
77 
ndisks 
dpbase 
77 


agsknxt 


asknxt 


=e 6 TO Q 





beginning of the uninitialize ram area above the bios, 

while the valve of “enddat" defines the next location 
following the end of the data area, the size ot this a, 
area 1S given by the value of "datsiz" at the end of t 
assembly. note that the allocation vector will be qui 

large if a large disk size is defined with a small blo 

size, 


macro dn 
define a single disk header list 


dw xXxlté&dn,dd0Gn stranslate table 

dw O0OVh, WO0bh *scratcn area 

dw dirbuf,dpb&dn sGir buff,parm block 
dw csv&an,alvédn scheck, alloc vectors 
endam 


macro nd 
define nd disks 


set nd *efor later reference 

equ S$ sbase of disk parameter blocks 
generate the nd elements 

set J 

rept nd 

dskhdr %dsknxt 

set dsknxct+l 

endm 

endm 

macro dn wy 
equ S *Gisk parm block 

endm 


macro data,comment 

define a db statement 

db data comment 
endm 


macro data,comment 

define a dw statement 

dw data comment 
endm 


macro m,n 

greatest common divisor of m,n 

produces value acdn as result 

(used in sector translate table generation) 


set m *evariable for m 

set n eevariable for n 

set 4) *svariable for r 

rept 65535 

set gcdm/gcdn 

set gcdm - gcdx*gcdn 

if gcdr = g 

exitm | 
endif ~~ 
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189: gcdm 
116: gcdn 
lil 

112 

£i3¢ 3 

114: diskdef 
£15 37"4:4 

116 

Lists 

118: dpbé&dn 
119: als&dn 
126: css&dn 
121: xlt&dn 
122 

123: secmax 
124: sectors 
125: als&dn 
126 

127: alsé&dn 
1238 

129: css&dn 
130: 3:3 

131: blkval 
132: blikshf 
133: blkmsk 
134 

135 

136 

137 

2303 ve 

139: blkshf 
140: olkmsk 
141: blkval 
142 

L433: +3; 

144: plkval 
145: extmsk 
146 

147 

148 

149 

150: 3:3 
151: extmsk 
152: pblkval 
153 

154: 3:; 

155 

156: extmsk 
157 

2562 23 

159 

160: extmsk 
161: 

162: 3; 
163: dirrem 


set gcdn 

set gcdr 

endm 

endm 

macro dn,fsc,lsc,skf,bls,dks;,dir,cks,ofs,kl6é 


generate the set statements for later tables 
if nul lsc 
current disk dn same as vrevious fsc 


equ dpb&fsc ;eauivalent parameters 

equ als&fsc ;same allocation vector size 
equ css&f£sc :;same checksum vector size 
equ xlt&fsc ;same translate table 

else 

set lsc-(fsc) *s-sectors #@...secmax 
set secmaxtl;:snumber of sectors 

set (dks) /8 ;;size of allocation vector 
if ((dks) mod os) ne g 

set als&dnt+l 

endif 

set (cks)/4 3;;number of checksum elements 
generate the block shift value 

set b1s/128 :;number of sectors/block 
set Gg *ecounts right @'s in blkval 
set G serills with 1's from right: 
rept 16 *sonce for each bit position 
Lf blkval=l } 

exitm 

endif 

otherwise, high order 1 not found yet 

set blkshf+l 

set (olkmsk shl 1) or 1 

set blkval/2 

endm 

generate the extent mask byte 

set b1s/1624 sz:number of kilobytes/block 
set Q >:;fiil from right with l'‘s 
rept 16 

if blkval=1 

exitm 

endif 

otherwise more to snift 

set (extmsk shl 1) or 1 

set blkval/2 

endm 

may be double byte allocation 

if (dks) > 256 

set (extmsk shr 1) 

endif 

may be optional [@] in last position 

if not nul kl6 

set k16 

endif 


now generate directory reservation bit vector 
set dir >;# remaining to process 
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dirbks 
dirblk 


dirrem 


dirrem 


ee 
oo 


xlt&dn 


xlt&dn 
,? 

nxtsec 
nxtbas 


nxtsec 
nxtsec 


nelts 


set 
set 
rept 
if 
exitm 
endif 


not complete, 


bls/32 ;;number of entries per block 

") -:;fi11 with 1's on each loop 

16 . J 
dirrem=¢ 


iterate once again 


shift right and add i high order bit 


set (dirblk shr 1) or 8900h 

if dirrem > dirbks 

set dirrem-dirbks 

else 

set ) 

endif 

endm 

dpbhdr dn *sgenerate egu §$ 

ddw $sectors,<;sec per track> 

ddb $oblkshf,<;:blcck shift> 

ddb $oblkmsk,<;bleck mask> 

ddb $extmsk,<;extnt mask> 

ddw $(dks)-1,<;aisk size-l> 

ddw $(dir)-l1,<;airectory max> 

ddb $dirbdlk shr 8,<;:alloc@é> 

ddb $dirblk ana Offh,<;allocl> 

ddw $(cks)/4,<;check size> 

ddw ofs,<;:offset> 

generate the translate table, if requested 
if nul skf | 
equ ” sno xlate table wy 
else 

Le skf = @ 

equ 7) eno xlate table 
else 

generate the translate table 

set ) ssnext sector to fill 

set ") *smcves by one on overflow 
gcd $sectors,skf 

gcdn = gcd(sectors,skew) 

set sectors/gcdn 

neltst is number of elements to generate 
before we overlap orevious elements 

set neltst ;;ccunter 

equ $ stranslate table 
rept sectors ;;once for each sector 

if sectors < 256 

ddb $nxtsect+(fsc) 

else 

ddw é$nxtsect(fsc) 

endif 

set nxtsect+(skf£) 

if nxtsec >= sectors 

set nxtsec-sectors 

endif 

set nelts-l | 
5 nelts = g — 
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219: nxtbas 
226: nxtsec 
221: nelts 
222 

223 

224 

225: 

226 

£283 

228: defds 
229: lab: 
236 

25134 

232: lds 
233 

234: 

2352 4 

236: endet 
231% 3 

238: begdat 
239: dirbuf: 
Z40: asknxt 
241: 

242 

243 

244: dsknxt 
245 

246: enddat 
247: datsiz 
2463+ 
249: 


set 
set 
set 
endif 
endm 
endif 
endif 
endm 


macro 
das 
endm 
macro 
aefds 
endm 


macro 


nxtbastl 
nxtbas 
neltst 


*esend of nul fac test 
esend of nul bls test 


lab,space 
space 


lb,dn,val 
lb&dn, ¢val&dn 


generate the nec2ssary ram data areas 


egu 
ds 
set 
rept 
las 
lds 
set 
endm 
equ 
equ 


S 

128 sdirectory access buffer 
4) 

ndisks ;;once for eacn disk 
alv,*dsknxt,als 

csv,%sdsknxt,css 

dsknxtt+l 


S 
S-begdat 


db @ at this point forces hex record 


endm 
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53: 





APPENDIX G: BLOCKING AND DEBLOCKING ALGORITHMS, 


e KRKKKKKKKKKKKKEKKKKKKKKKKEKKKEKKKRKEKKKKREKERKEKKEKKEKKKEKEKE 


o * * 
iad Sector Deblocking Algorithms for CP/M 2.9 * 
ox * 
BCCI COCO IOG ICICI IOCIIOCI ICCC ICCC TCC CICUICIIO ITO Ik 
: utility macro to compute sector mask 
smask macro hblk 
es compute log2(hblk), return @x as result 
2 (2 ** @x = hblk on return) 
@y set hb1k 
@x set Q 
oe count right shifts of @y until = 1 
rept 8 
if @y = 1 
exitm 
endif 
a @y is not l, shift right one position 
@y set @y shr 1 
@x set @x + ] 
endm 
endm 


KREEKEKKKEKKEKKKEKRKRERKEKEKKKEKRREREKKEKRRREKEKEKRKRKKKRKRKKRKRKKKEK 


e@ ~e se ~e we 
+ + F 


* 
CP/M to host disk constants - 
* * 
RICCI IOI ICOO ICCC ICCC ICOCCI IOUT ICCC RTO I IK 
blksiz equ 2048 *CP/M allocation size 
hstsiz equ 512 shost disk sector size 
hstspt equ 20 ;host disk sectors/trk 
hstblk equ hstsiz/128 ;CP/M sects/host buff 
cpmspt equ hstblk * hstspt ;CP/M sectors/track 
secmsk equ hstblk-1 ;sector mask 
smask hstblk ;compute sector mask 
secshf equ @x ;log2(hstblk) 
DIGGS ICICI OGISOCI CI TOCIIOCICCICOICI TOI TOI IOI Ik 
x * 
ie BDOS constants on entry to write = 
ex * 
RICCO ICICI TOO ICG ICOI ICO GCOS ICI IIIT k 
wrall equ Y) swrite to allocated 
wrdir equ 1 ;write to directory 
wrual egu 2 swrite to unallocated 


e 
0 


e KKK KKKKKK KK KK KKEKKKKEKKEKKEKKKKKEKKKKKKKEKKEKKKEKKEEKKKEKKKEKKS 


oX* rs 
ce The BDOS entry points given below show the * 
* code which is relevant to deblocking only. * 
ox * 


U] 
CRKEKKKEKKEKEKEKKEKKREKREKEKKEEKRKKKREKEKREKKKRREKRKREKKRKRKKRKKRREKE 


a 
e 
v 
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seldsk: 


e 
g 


settrk: 


e 
a 


setsec: 


e 
0 


setdma: 


H 
sectran: 


DISKDEF macro, or hand coded tables go here 
equ $ edisk param block base 


eenter here on system boot to initialize 


xra a °@ to accumulator 

sta hstact shost buffer inactive 
sta unacnt eclear unalloc count 
ret 


*select disk 


Mov a,c sselected disk number 

sta sekdsk sseek disk number 

mov 1l,a disk number to HL 

mvi h,@ 

rept & smultiply by 16 

dad h 

endm 

1xi d,dpbase ;base of parm block 

dad d ;hl=,dpb(curdsk) | 
ret | 


set track given by registers BC 


mov h,b 

mov Los 

shld sektrk etrack to seek 
ret 


eset sector given by register c 


mov a,c 
sta seksec ssector to seek 
ret 


set dma address given by BC 





mov h,b 

mov iP: 

shld dmaadr 

ret 

etranslate sector number BC 
mMOv h,b 

mov byt 

ret 
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e REKRRKKEKEKKREKAREKRERRERERREREKEKEREREREKREEEKERUERRERERE 


* 
The READ entry point takes the place of * ad 
the previous BIOS defintion for READ, sd 


* 


e RRREKEKREKERKEREREREKAKRERERERRERERERERRERERKRKRERERE 


read: 


=e CO WOE WO WE 
+ + + 


= @ 
+ 


eread the selected CP/M sector 


mvi ay dL 

sta readop sread operation 

sta rsflag s;must read data 

mvi a,wrual 

sta wrtype ;treat as unalloc 
jmp rwoper ;to perform the read 


KKEEKKKEKKKEKREKRKEEKREKKKKKKKKRKEKEKRKRKEKEKEKKKKEKRKKKEKEKKEKKKKKKKKE 


# 
The WRITE entry point takes the place of . 
the previous BIOS defintion for WRITE, : 


* 


e RKKKKKKKKEKKKEK KKK KEKE KKEKKK KEK KKEKKKKKEKKKKKEKEKKKKKKKKKKE 


write: 


=e Oe 


e 
v 


chkuna: 


=e Oe 


=e 6 


ewrite the selected CP/M sector 


Xxra a °-@ to accumulator 

sta readop snot a read operation 

MOV a3 swrite type inc 

Sta wrtype 

cpl wrual *write unallocated? —, 
jnz chkuna check for unalloc 


write to unallocated, set parameters 


mv1 a,blksiz/128 enext unalloc recs 
sta unacnt 

lda sekdsk disk to seek 

sta unadsk sunadsk = sekdsk 
lhid sektrk 

shld unatrk eunatrk = sectrk 
lda seksec 

sta unasec sunasec = seksec 


echeck for write to unallocated sector 


lda unacnt sany unalloc remain? 
ora a 
jz alloc skip if not 


more unallocated records remain 


der a eunacnt = unacnt-l 
sta unacnt 

lda sekdsk ‘Same disk? 

1x1 h,unadsk 

cmp m ;sekdsk = unadsk? 
jnz alloc skip if not 


disks are the same 
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1x1 h,unatrk 
call sektrkcmp ssektrk = unatrk? 
jnz alloc skip if not 


=e TO 


tracks are the same 


lda seksec *same sector? 
1x1 h,unasec 
cmp m sseksec = unasec? 
jnz alloc skip if not 

0 

° match, move to next sector for future ref 
inr m eunasec = unasectl 
mov a,m send of track? 
cpl cpmspt -count CP/M sectors 
ze. noovf sskip if no overflow 


=e TO 


overflow to next track 


mvi m,@ eunasec = Q@ 

lhid unatrk 

inx h 

shld unatrk eunatrk = unatrk+l 
’ 
nooveE: 

smatch found, mark aS unnecessary read 

xra a “8 to accumulator 

sta rsflag ersflag = @ 

jmp rwoper sto perform the write 
alloc: 

snot an unallocated record, requires pre-read 

xra Al °@ to accum 

sta unacnt sunacnt = Q 

inr a el to accum 

sta rsflag srsflag = l 
DIGIC IOI ICICI IOGIGIGIOISSIOII ICICI GIGI TCC IOI TCG 
eX * 
v 
gl Common code for READ and WRITE follows * 
e * * 
| 


eC KKKKKEKKEKKEK KKK KEKE KEKE KE KKEKKKEKKKKEKKEKKKKKEKKEKKEKEKKEKKKKEKER 
rwoper: 
senter here to perform the read/write 


xra a ;zero to accum 

sta erflag sno errors (yet) 

lda seksec compute host sector 

rept secshf 

ora a scarry = @ 

rar shift right 

endm 

sta sekhst. shost sector to seek 
0 
: active host sector? 

1xi h,hstact shost active flag 

mov a,m 

mvi m,1 ;always becomes 1] 
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=e ~O 


-=e WO 


7 
nomatch: 


filhst: 


¢ match: 


™~e 


ora a swas it already? 
jz filhst fill host if not 
WT 
host buffer active, same as seek buffer? 
lda sekdsk 
1xi h,hstdsk *same disk? 
cmp m esekdsk = hstdsk? 
nz nomatch 
same disk, same track? 
1xi h,hsttrk . 
call sektrkcmp esektrk = hsttrk? 7 
jnz nomatch 
same disk, same track, same buffer? 
lda sekhst 
1xi h,hstsec ssekhst = hstsec? 
cmp m 
IZ match skip if match 
sproper disk, but not correct sector 
lda hstwrt shost written? 
ora a 
cnz writehst eclear host buff 
smay have to fill the host buffer 
lda sekdsk ~ 
sta hstdsk 
lhld sektrk 
shld hsttrk 
lda sekhst 
sta hstsec 
lda rsflag sneed to read? 
ora a 
cnz readhst syes, if l 
Xra a 7@ to accum 
sta hstwrt sno pending write 
scopy data to or from buffer 
lda seksec emask buffer number 
ani secmsk sleast signif bits 
mov l,a sready to shift 
mv1 h,@ sdouble count 
rept 7 shift left 7 
dad h 
endm 
hl has relative host buffer address 
1x1 d,hstbuf 
dad d ehl = host address 
xchg snow in DE 
lhid dmaadr ;get/put CP/M data og 
mvi c,128 slength of move 
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=e SO 


rwmove ¢ 


=o 6 


=e BO 


* 
* 
* 
* 
* 


=e =e %=6 |=6 6TO TO 


lda 
ora 
jnz 


readop 
a 
rwmove 


swhich way? 


sskip iff read 


write operation, mark and switch direction 


mvi 
sta 
xchg 


7C initially 128, DE is 


ldax 
inx 
mov 
inx 
dcr 
jnz 


a,l 
hstwrt 


ra 


qaqmvms ad, 


rwmove 


shstwrt = 1 
ssource/dest swap 


source, HL is dest 
“source character | 
eto dest 


sloop 128 times 


data has been moved to/from host buffer 


lda 
cpl 
lda 
rnz 


clear host buffer for directory write 


ora 
rnz 
Xra 
sta 
call 
lda 
ret 


Utility subroutine for 16-bit compare 4 


sektrkcmp: 


=e 


sHL = .unatrk or .hsttrk, compare with sektrk 


xchg 
1xi 
ldax 
cmp 
rnz 
low 
inx 
inx 
ldax 
cmp 
ret 


wrtype 
wrdir 
erflag 


a 


a 


hstwrt 
writehst 


erflag 


KEKKEKKEKKEKKKEKKKEKKEKKEKEKEKKEEKKEKEKEKEKRKEKKERKEKRKKEKEKEKEKKE 


h,sektrk 


d 
m 


swrite type 

sto directory? 

sin case of errors 

sno further processing 


errors? | 
sskip if so 
°*@ to accum 
ebuffer written 


KKEKEKKKKEEKKEEKEKKEKREKEKEKKERRERKKREREKEKRKKKEKRKEKEKKKEKKESE 


* 


* 


;low byte compare 
*same? 
ereturn if not 





bytes equal, test high ls 


30a 5 & 


ssets flags 
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REEKKEKKEKKKEKEKEKKEKKEKKRKEEKRKEKEKKKEKERKEKKEKKEEKRKKRKRKKKEKRE 


* 
WRITEHST performs the physical write to - 
the host disk, READHST reads the physical 2 
disk. Xd 
* 
* 


me ~e we Ne tO 
+ + + H& F 


=e 
* 


o RKKEKKKKEKKEEKEKRKEKEEKE RE KKERKEREKEEKEKKEEEREKEERERREKREKKRKEK 


328: writehst: 

329: shstdsk = host disk #, hsttrk = host track #, 
338: shstsec = host sect #. write "“hstsiz" bytes 
a54% >from hstbuf and return error flag in erflag. 
332: sreturn erflag non-zero if error 

333: ret 

334: : 

335: readhst: 

336: shstdsk = host disk #, hsttrk = host track #, 
a I ;hstsec = host sect #., read “hstsiz" bytes 
338: sinto hstbuf and return error flag in erflag. 
339: ret 

340: ; 

341: o KKEKKEKREREKKKEKRESEREREREEKRERRERRRERERE RAR ERREEREREREREE 
342: ;* * 
343: ;* Unitialized RAM data areas * 
344: ;* * 
345: o RHEKKKKKKEKKEKKKKER KEE KERR ERR EER EKER AREEREKREREKKKEKE 
346: ;: 

347: sekdsk: ds ] eseek disk number 

348: sektrk: ds 2 sseek track number 

349: seksec: ds 1] eseek sector number 
3582 3 

351: hstdsk: ds 1 shost disk number 

352: hsttrk: ds 2 sehost track number 

353: hstsec: ds 1 ehost sector number 
354: ; 

355: sekhst: ds 1 esseek shr secshf 

356: hstact: ds 1 shost active flag 

357: hstwrt: ds 1 shost written flag 
3505) * 

359: unacnts: ds 1 sunalloc rec cnt 

360: unadsk: ds 1 slast unalloc disk 
361: unatrk: ds 2 eslast unalloc track 
362: unasec: ds 1 eslast unalloc sector 
363: ; 

364: erflaag: ds 1 serror reporting 

365: rsflag: ds 1 sread sector flag 

366: readov: ds 1 71 if read operation 
367: wrtype: ds E swrite operation type 
368: dmaadr: ds 2 *last dma address 

369: hstbuf: ds hstsiz shost buffer 

370: ; 
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371: e RKKKKKKKKKKKKKKKKKKEK KEKE KKEKEKKEKKKEKKEEKEKEKKKKKKKKKKKKEK 
372: 3* te 
ce ie fae aad The ENDEF macro invocation goes here > 
374: 3* & 
375: e RKKKKKKKKKKKKKEKKK KEKE KKK RKKKEKKEKKEKEKREKEKEEKRERKEKKKKKKKKEE 


376: end 
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1. INTRODUCTION, 


This manual describes CP/M, release 2, system organization 
including the structure of memory and system entry points. The 
intention is to provide the necessary information required to write 
programs which operate under CP/M, and which use the peripheral and 
disk I/O facilities of the system. 


CP/M is logically divided into four parts, called the Basic I/O 
System (BIOS), the Basic Disk Operating System (BDOS), the Console 
command processor (CCP), and the Transient Program Area (TPA). The 
BIOS is a hardware-dependent module which defines the exact low level 
interface to a particular computer system which is necessary for 
peripheral device I/O. Although a standard BIOS is supplied by 
Digital Research, explicit instructions are provided for field 
reconfiguration of the BIOS to match nearly any hardware environment 
(see the Digital Research manual entitled "CP/M Alteration Guide"). 
The BIOS and BDOS are logically combined into a single module with a 
common entry point, and referred to as the FDOS. The CCP is a 
distinct program which uses the FDOS to provide a human-oriented 
interface to the information which is cataloged on the backup storage 
device, The TPA is an area of memory (i.e., the portion which is not 
used by the FDOS and CCP) where various non-resident operating system 
commands and user programs are executed, The lower portion of memory 
is reserved for system information and is detailed later sections, 
Memory organization of the CP/M system in shown below: 


high | | 
memory | | 
| FDOS (BDOS+BIOS) | 
FBASE: | | 
| | 
| CCP | 
CBASE: | | 
| | 
| | 
| | 
| TPA | 
| | 
TBASE: | | 
| system parameters 

BOOT: | 


The exact memory addresses corresponding to BOOT, TBASE, CBASE, and 
FBASE vary from version to version, and are described fully in the 
“CP/M Alteration Guide." All standard CP/M versions, however, assume 
BOOT = @@80H, which is the base of random access memory. The machine 
code found at location BOOT performs a system “warm start" which loads 
and initializes the programs and variables necessary to return control 
to the CCP. Thus, transient programs need only jump to location BOOT 


(All Information Contained Herein is Proprietary to Digital Research.) 
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to return control to CP/M at the command level. Further, the standard 
versions assume TBASE = BOOT+@1@@H which is normally location @190H, 
The principal entry point to the FDOS is at location BOOT+8@05H 
(normally 9@095H) where a jump to FBASE is found, The address field at 
BOOT+@086H (normally @@#6H) contains the value of FBASE and can be 
used to determine the size of available memory, assuming the CCP is 
being overlayed by a transient program. 


Transient programs are loaded into the TPA and executed as 
follows. The operator communicates with the CCP by typing command 
lines following each prompt. Each command line takes one of the 
forms: 


command 
command filel 
command filel file2 


where “command" is either a built-in function such as DIR or TYPE, or 
the name of a transient command or program. If the command is a 
built-in function of CP/M, it is executed immediately. Otherwise, the 
CCP searches the currently addressed disk for a file by the name 


command, COM 


If the file is found, it is assumed to be a memory image of a program 
which executes in the TPA, and thus implicitly originates at TBASE in 
memory. The CCP loads the COM file from the disk into memory starting 
at TBASE and possibly extending up to CBASE, 


If the command is followed by one or two file specifications, 
the CCP prepares one or two file control block (FCB) names in the 
System parameter area, These optional FCB's are in the form necessary 
to access files through the FDOS, and are described in the next 
section, 


The transient program receives control from the CCP and begins 
execution, perhaps using the I/O facilities of the FDOS. The 
transient program is “called" from the CCP, and thus can simply return 
to the CCP upon completion of its processing, or can jump to BOOT to 
pass control back to CP/M. In the first case, the transient program 
must not use memory above CBASE, while in the latter case, memory up 
through FBASE=-1 is free, 


The transient program may use the CP/M I/O facilities to 
communicate with the operator's console and peripheral devices, 
including the disk subsystem. The I/O system is accessed by passing a 
“function number" and an “information address" to CP/M through the 
FDOS entry point at BOOT+@@05H, In the case of a disk read, for 
example, the transient program sends the number corresponding to a 
disk read, along with the address of an FCB to the CP/M FDOS. The 
FDOS, in turn, performs the operation and returns with either a disk 
read completion indication or an error number indicating that the disk 
read was unsuccessful. The function numbers and error indicators are 
given in belo. 


(All Information Contained Herein is Proprietary to Digital Research.) 
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2. OPERATING SYSTEM CALL CONVENTIONS. 


The purpose of this section is to provide detailed information 
for performing direct operating system calls from user programs. Many 
of the functions listed below, however, are more simply accessed 
through the I/O macro library provided with the MAC macro assembler, 
and listed in the Digital Research manual entitled "MAC Macro 
Assembler: Language Manual and Applications Guide,” 


CP/M facilities which are available for access by transient 
programs fall into two general categories: simple device I/O, and 
disk file I/O. The simple device operations include: 


Read a Console Character 

Write a Console Character 

Read a Sequential Tape Character 
Write a Sequential Tape Character 
Write a List Device Character 
Get or Set I/O Status 

Print Console Buffer 

Read Console Buffer 

Interrogate Console Ready 


The FDOS operations which perform disk Input/Output are 


Disk System Reset 

Drive Selection 

File Creation 

File Open 

File Close 

Directory Search 

File Delete 

File Rename 

Random or Sequential Read 
Random or Sequential Write 
Interrogate Available Disks 
Interrogate Selected Disk 
Set DMA Address 

Set/Reset File Indicators 


As mentioned above, access to the FDOS functions is accomplished 
by passing a function number and information address through the 
primary entry point at location BOOT+@9@05H, In general, the function 
number is passed in register C with the information address in the 
double byte pair DE. Single byte values are returned in register A, 
with double byte values returned in HL (a zero value is returned when 
the function number is out of range). For reasons of compatibility, 
register A = L and register B = H upon return in all cases. Note that 
the register passing conventions of CP/M agree with those of Intel's 
PL/M systems programming language. The list of CP/M function numbers 
1s given below. 
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0 System Reset 19 Delete File 

1 Console Input 26 Read Seguential 

2 Console Output 21 Write Sequential 

3 Reader Input 22 Make File 

4 Punch Output 23 Rename File 

> List Output 24 Return Login Vector 

6 Direct Console I/0 25 Return Current Disk 

7 Get I/O Byte 26 Set DMA Address 

8 Set I/O Byte 27 Get Addr(Alloc) 

9 Print String 28 Write Protect Disk 
1@ Read Console Buffer 29 Get R/O Vector 

ll Get Console Status 3@ Set File Attributes 
12 Return Version Number 31 Get Addr(Disk Parms) 
13 Reset Disk System 32 Set/Get User Code 
14 Select Disk 33 Read Random 
15 Open File 34 Write Random 
l6é Close File 35 Compute File Size 
17 Search for First 36 Set Random Record 


18 Search for Next 


(Functions 28 and 32 should be avoided in application programs’ to 
maintain upward compatibility with MP/M.) 


Upon entry to a transient program, the CCP leaves the stack 
pointer set to an eight level stack area with the CCP return address 
pushed onto the stack, leaving seven levels before overflow occurs. 
Although this stack is usually not used by a transient program (i.e., 
most transients return to the CCP though a jump to location @900H), it 
is sufficiently large to make CP/M system calls since the FDOS 
Switches to a local stack at system entry. The following assembly 
language program segment, for example, reads characters continuously 
until an asterisk is encountered, at whicn time control returns to the 
CCP (assuming a standard CP/M system with BOOT = @@00H): 


BDOS EQU G9 O5H ;STANDARD CP/M ENTRY 
CONIN EQU 1 ;CONSOLE INPUT FUNCTION 
ORG W100H 7;BASE OF TPA 
NEXTC: MVI C,CONIN ;READ NEXT CHARACTER 
CALL BDOS ;RETURN CHARACTER IN <A> 
CPI ie! >END OF PROCESSING? 
JNZ NEXTC ;LOOP IF NOT 
RET ;RETURN TO CCP 
END 


CP/M implements a named file structure on each disk, providing a 
logical organization which allows any particular file to contain any 
number of records from completely empty, to the full capacity of the 
drive. Each drive is logically distinct with a disk directory and 
file data area, The disk file names are in three parts: the drive 
select code, the file name consisting of one to eight non-blank 
Characters, and the file type consisting of zero to three non-blank 
Characters, The file type names the generic category of a particular 
file, while the file name distinguishes individual files in each 
category. The file types listed below name a few generic categories 
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which have been established, although they are generally arbitrary: 


ASM Assembler Source PLI PL/I Source File 

PRN Printer Listing REL Relocatable Module 
HEX Hex Machine Code TEX TEX Formatter Source 
BAS Basic Source File BAK ED Source Backup 
INT Intermediate Code SYM SID Symbol File 

COM CCP Command File $$$ Temporary File 


Source files are treated as a sequence of ASCII characters, where each 
"line" of the source file is followed by a carriage-return line-feed 
sequence (@DH followed by OAH). Thus one 128 byte CP/M record could 
contain several lines of source text. The end of an ASCII file is 
denoted by a control-Z character (1AH) or a real end of file, returned 
by the CP/M read operation, Control-Z characters embedded within 
machine code files (e.g., COM files) are ignored, however, and the end 
of file condition returned by CP/M is used to terminate read 
operations. 


Files in CP/M can be thought of as a sequence of up to 65536 
records of 128 bytes each, numbered from @ through 65535, thus 
allowing a maximum of 8 megabytes per file, Note, however, that 
although the records may be considered logically contiguous, they may 
not be physically contiguous in the disk data area, Internally, all 
files are broken into 16K byte segments called logical extents, so 
that counters are easily maintained as 8-bit values, Although the 
decomposition into extents is discussed in the paragraphs which 
follow, they are of no particular consequence to the programmer’ since 
each extent is automatically accessed in both sequential and random 
access modes, 


| In the file operations starting with function number 15, DE 
usually addresses a file control block (FCB). Transient programs 
often use the default file control block area reserved by CP/M at 
location BOOT+@@5CH (normally @@5CH) for simple file operations, The 
basic unit of file information is a 128 byte record used for all file 
operations, thus a default location for disk I/O is provided by CP/M 
at location BOOT+®#980H (normally ®9080H) which is the initial default 
DMA address (see function 26). All directory operations take place in 
a reserved area which does not affect write buffers as was the case in 
release 1, with the exception of Search First and Search Next, where 
compatibility is required, 


The File Control Block (FCB) data area consists of a sequence of 
33 bytes for sequential access and a series of 36 bytes in the case 
that the file is accessed randomly. The default file control block 
normally located at @85CH can be used for random access files, since 
the three bytes starting at BOOT+@@7DH are available for this purpose, 
The FCB format is shown with the following fields: 
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“9g O12 22.4 06 89 10 11 22 23°34 25 6 we 2h 32 3534-55 
where 


dr drive code (@ - 16) 
@ => use default drive for file 


l => auto disk select drive A, 
2 => auto disk select drive B, 


16=> auto disk select drive P. 


at Rei ae = contain the file name in ASCII 
upper case, with high bit = @ 


tl,t2,t3 contain the file type in ASCII 


upper case, with high bit = @ 
tl’, t2', and t3' denote the 
bit of these positions, 


tl’ = 1 => Read/Only file, 
t2' = 1 => SYS file, no DIR list 
ex contains the current extent number, 


normally set to 9@ by the user, but 
in range @ - 31 during file I/0 


sl reserved for internal system use 


S2 reserved for internal system use, set 
to zero on call to OPEN, MAKE, SEARCH 


rc record count for extent “ex,” 
takes on values from @ - 128 


d@...dn filled-in by CP/M, reserved for 
system use 


cr Current record to read or write in 


a sequential file operation, normally 
set to zero by user 


r@,rl,r2 optional random record number in the 
range @-65535, with overflow to r2, 
r0,rl constitute a 16-bit value with 
low byte r@, and high byte rl 


Each file being accessed through CP/M must have a_ corresponding 
FCB which provides the name and allocation information for all 
subseguent file operations, When accessing files, it is the 
programmer's responsibility to fill the lower sixteen bytes of the FCB 
and initialize the "cr" field. Normally, bytes 1 through 11 are _ set 
to the ASCII character values for the file name and file type, while 
all other fields are zero. 
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FCB's are stored ina directory area of the disk, and are 
brought into central memory before proceeding with file operations 
(see the OPEN and MAKE functions). The memory copy of the FCB is 
updated as file operations take place and later recorded permanently 
on disk at the termination of the file operation (see the CLOSE 
command), 


The CCP constructs the first sixteen bytes of two optional FCB's 
for a transient by scanning the remainder of the line following the 
transient name, denoted by "“filel" and "file2" in the prototype 
command line described above, with unspecified fields set to ASCII 
blanks. The first FCB is constructed at location BOOT+@95CH, and can 
be used as-is for subsequent file operations. The second FCB occupies 
the d@ ... dn portion of the first FCB, and must be moved to another 
area Of memory before use, If, for example, the operator types 


PROGNAME B:X.ZOT Y.ZAP 


the file PROGNAME.COM is loaded into the TPA, and the default FCB at 
BOOT+@@5CH is initialized to drive code 2, file name "X" and file type 
uO gue The second drive code takes the default value @, which is 
placed at BOOT+@@6CH, with the file name "Y" placed into location 
BOOT+@@6DH and file type "ZAP" located 8 bytes later at BOOT+@075H. 
All remaining fields through "cr" are set to zero. Note again that it 
is the programmer's responsibility to move this second file name _ and 
type to another area, usually a separate file control block, before 
opening the file which begins at BOOT+@@5CH, due to the fact that the 
open operation will overwrite the second name and type. 


If no file names are specified in the original command, then the 
fields beginning at BOOT+#@5DH and BOOT+@®86DH contain blanks. In all 
cases, the CCP translates lower case alphabetics to upper case to be 
consistent with the CP/M file naming conventions, 


As an added convenience, the default buffer area at location 
BOOT+@@8@H 1S initialized to the commana line tail typed by the 
operator following the program name. The first position contains’ the 
number of characters, with the characters themselves following the 
Character count. Given the above command line, the area beginning at 
BOOT+G080H 1S initialized as follows: 


BOOT+9@080H: 
+00 +01 +62 +093 +04 +05 +06 +07 +08 +09 +10 +11 +12 +13 +14 
] 4 be te ee B 60 06 ° oe v6 X a8 ve . bo és 7, v6 te Oo" uf dha iT) ve be Y be iT) : be ve 7 Ty te A be ve Pp be 


where the characters are translated to uoper case ASCII with 
uninitialized memory following the last valid character. Again, it is 
the responsibility of the programmer to extract the information from 
this buffer before any file operations are performed, unless the 
default DMA address is explicitly changed, 


The individual functions are described in detail in the pages 
which follam. 


(All Information Contained Herein is Proprietary to Digital Research. ) 
7 








KREKKKKKKKKEKKKKKEKKKEKKEKEKKEKKKEKKKKKKKKKKEKE 


* * 
* FUNCTION @: System Reset * 
* * 
KHEEKKKKEKKEKKEKKKKKEKKKKKKKKKKKKRKRKKKKKKKRKEEK \ d 
* Entry Parameters: . 
- Register C: O@H x 


RREEKKKKKKKKEKKEKKEKKKKKKEKKEKKKKEKRKKKKKKEKKKKE 


Tne syStem reset function returns control to the CP/M operating 
System at the CCP level. The CCP re-initializes the disk subsystem by 
selecting and logging-in disk drive A. This function has exactly the 
same effect as a jump to location BOOT, 


KREKKKKKKEKKKKKKKEKKKEKKKEKKKKKKKKEKKKKKKKKE 


* * 
* FUNCTION 1: CONSOLE INPUT : 
* * 
KREEKKKKKEKKKKKKKKKKKKRKRKKRKRKKRKKKRKKRKRKRKRKKRKEK 
* Entry Parameters: e 
: Register C: #18 m 
x * 
* Returned Value: * 
x Register A: ASCII Character * 
KREAEKKEKKKKEKKEKKKKKRKEKRKKKRKKKKKRKRKKKKRKKKRKRKRKKRE 


The console input function reads the next console character to 
reqister A, Graphic characters, along with carriage return, line 
feed, and backspace (ctl-H) are echoed to the console, Tab characters | 
(ctl-I) are expanded in columns of eight characters, A check is’ made ~~ 
for start/stop scroll (ctl-S) and start/stop printer ecno (ctl-P). 
The FDOS does not return to the calling program until a character has 
been typed, thus suspending execution if a character is not ready. 


KRREKRKEKKEKKKKKEKKEKKKKKKKKKKKEKKEKKKEKKKKKKKKESR 


* * 
* FUNCTION 2: CONSOLE OUTPUT * 
* * 
KREKEKKKKKKEKKEKKKKKKKKKEKKRKEKEKRKKKKKKKKRKKRKKEKEE 
* Entry Parameters: . 
t Reqister Ce 62H - 
x Register E: ASCII Character * 
* * 


KREKEKKEKKKKKKKKKKEKKKKEKEKKKEKKEKKKKKEKKKKKKKEKE 


The ASCII character from register E is sent to the console 
device, Similar to function 1, tabs are expanded and checks are made 
for start/stop scroll and printer echo. 
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KHEKEKEKKKKKEKKKEKEKKKKKKEKEKEKKEKKKEKEKKEKRKKKKKEEE 


* * 
* FUNCTION 3: READER INPUT * 
* * 
KRRKEKKEKKKKKKKKEEKKEKREKKEKKEKKKRERKKEKKKRKEKER 
* Entry Parameters: : 
* Register Cs-- OSH * 
* * 
* Returned Value: 
* Register As ASCII Character * 
KKEKKKEKEKEKKKEKKKEKRKKEKKKKEKRKEKKRKKKKEEKKEEERKEK 


The Reader Input function reads the next character from the 
logical reader into register A (see the IOBYTE definition in the "CP/M 
Alteration Guide"), Control does not return until the character has 
been read, 


KRREEKKKEKKKEKKEKKEKKEKKEKKEKKKKRKKKKKKEKKEKKEKKKE 


* * 
* FUNCTION 4: PUNCH OUTPUT * 
* * 
KREKEKKEKKERKKEKEKKKKEKKEKKKEKRKEKEEKKEKEKKRKKKRKEKKEE 
* Entry Parameters: 3 
i Register C: 64H i 
* Register E: ASCII Character * 
* * 


KREKEKEKKEKKEKKEKEKKKKEKKKEKKEKKKEEKKKEKEKKKEKKKREKE 


The Punch Output function sends the character from register E to 
the logical punch device, 


KEEKKKKKKEKKKKEKEKEKKEKKEKKKKEKKEKEKKEKKKEKKKEKSE 


* * 
* FUNCTION 5: LIST OUTPUT * 
* * 
KREEKKKKKKKEKKKKEEKKEREKKEKKKEKEKKKRKKEKKKKEE 
* Entry Parameters: . 
. Register C: @5H ™ 
n Register E: ASCII Character * 
* * 


KRREEKKKKEKKKEKEKKEKKEKEKKEKEKKEKKEKKKRKEKKEKEKKEKKKE 


The List Output function sends the ASCII character in register E 
to the logical listing device, 
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RREKKKEKEKKKEKKKEKEKEKKEKKEKEKKEKKEKKRKKKRKRKKKRRKRKKKEKK 


ge * 
* FUNCTION 6: DIRECT CONSOLE I/O 
* 
KEKE KKEKKKKKKKEEKEKKKKEKREKRKKKKKRKKRKRKRKKKRKRKEK 
* Entry Parameters: e 
* Register C: 6H % 
z Register E: OFFH (input) or * 
* char (output) . 
* * 
* Returned Value: * 
2 Register A: char or status * 
(no value) * 
KREEKKKKKKKKEKKEKKKEKEKKEKKKEKRKKEKEKKEKEKKKKKRKEKE 


Direct console I/O is supported under CP/M for those specialized 
applications where unadorned console input and output is’ required, 
Use of this function should, in general, be avoided since it bypasses 
all of CP/M's normal control character functions (e.g., control-S and 
CONELOI=P).. Programs which perform direct I/O through the BIOS under 
previous releases of CP/M, however, should be changed to use direct 
I/O under BDOS so that they can be fully supported under future 
releases of MP/M and CP/M, 


Upon entry to function 6, register E either contains hexadecimal 
FF, denoting a console input reguest, or register E contains an ASCII 
character, If the input value is FF, then function 6 returns A = @@ 
if no character is ready, otherwise A contains the next console input 
character. 


If the input value in E is not FF, then function 6 assumes’ that 
E contains a valid ASCII character which is sent to the console, 
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KREKEKKEKEKEKKEKKEREKKEKKEKKEKREKREKEKKEKKEKKKRKKKESK 


* * 
* ‘ e i * 
a, ‘ FUNCTION 7: GET I/O BYTE : 
KHEKKKKKK KKK KKKEKKKKEKEKEKKEKKEKKKKKEKKRKKKEKKK 
* Entry Parameters: " 
i Register C: 7H x 
* * 
* Returned Value: - 
. Register A: I/O Byte Value * 
KKEKKKKKKKEKKKKEKKEKKEEKKEKEKKEKKKEKKEKKKEKKKEEKKES 


The Get I/O Byte function returns the current value of IOBYTE in 
register A. See the "CP/M Alteration Guide" for IOBYTE definition, 


KRREEKKKKEKEKEKKKKKKKEKKKKKKKEKKKKKEKKKKEKKKKKK 


se * 
* FUNCTION 8: SET I/O BYTE ” 
* * 
KREEKKEKKEKKKKEEKKEKEKEKKRKEKEKRKRKEKEKREKKKKREE 
* Entry Parameters: - 
* Register C: 08H ag 
* Register E: I/O Byte Value * 
* * 


KRREEKEKRKKKEKEKKKEKKKKKKEKKEKKEEKKEKKEKKERKKRKKEKKEK 


The Set I/O Byte function changes the svstem IOBYTE value to 
in’ that given in register E, 


KKHEKKEKEKKKEKKKEKEKRKKEKKEKRKEKKEKKRKKKKRKEKKKRKKK 


* * 
* FUNCTION 9: PRINT STRING is 
* * 
HKRKKEKKEKKKEKKEKRKEKKKRKEKKEKKKEKKEKEKEKKEKKKKKEKKEKE 
* Entry Parameters: * 
| Register Ge OSa = 
* Registers DE: String Address * 
* * 


KREEKKKKKEKKEKKKEKKEKKEKKEKKKEKEKKEKKKEKKEKKKKKKKEKK 


The Print String function sends the character string stored in 
memory at the location given by DE to the console device, until a “$" 
is encountered in the string. Tabs are expanded as in function 2, and 
checks are made for start/stop scroll and printer echo, 
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KRKEEKKKKKKEKKEKKEKKEKKEKEKEKEKKEKKEKKEKKEKEKKEESK 
* * 


* FUNCTION 10: READ CONSOLE BUFFER e 
x * 


KKKKKKKKEKKEKKKEKKEKKEKKEKEKKKEKKKKKEKEKKKKKRKKE 
* Entry Parameters: 

Register C: AH 

Registers DE: Buffer Address 


* 
* 
* 
* Returned Value: 
* 
* 


Console Characters in Buffer 
KRHEKKKKKKKEKEKKKKKKEKRKKKKKRKKKKKRKRKKKKKKKEE 


* 
* 
* 
* 
* 
* 
* 
The Read Buffer function reads a line of edited console input 
into a buffer addressed by registers DE. Console input is terminated 


when either the input buffer overflows. The Read Buffer takes’ the 
form: 


DE: +0 +1 +2 +3 +4 +5 +6 +7 +8 e. ww +n 


where "mx" is the maximum number of characters which the buffer will 
hold (1 to 255), "nce" is the number of characters read (set by FDOS 
upon return), followed by the characters read from the console. if nc 
< mx, then uninitialized positions follow the last character, denoted 
by "??" in the above figure, A number of control functions are 
recognized during line editing: 


rub/del removes and echoes the last character 
ctl-C reboots when at the beginning of line 
ctl-E causes physical end of line 

ctl-H backspaces one character position 

ctl-J (line feed) terminates input line 

ctl-M (return) terminates input line 

ctl-R retypes the current line after new line 
ctl-U removes currnt line after new line 
ctl-X backspaces to beginning of current line 


Note also that certain functions which return the carriage to the 
leftmost position (e.g., ctl-X) do so only to the column position 
where the prompt ended (in earlier releases, the carriage returned to 


the extreme left margin). This convention makes operator data input 
and line correction more legible, 
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KKEEKKKKEKEKKEKKKEKKEKKKEKKEKEEKKEKREKKEKRKKKRKKKKKSE 


x * 
* FUNCTION 11: GET CONSOLE STATUS - 
* * 


KHKKKKKKKEKRKEKEKKKKEKEKEKRKEKKEKEEKEKRKERKEKKKKKEKRKEE 


* Entry Parameters: * 
Register C: @BH 


Register A: Console Status 


* * 
* * 
* Returned Value: * 
* * 
KEEAEKKKKEKKKKKKEKKKRKEKRRKKKAKKRKKKEKKKRKRKEKSE 


The Console Status function checks to see if a character has 
been typed at the console, If a character is ready, the value @FFH is 
returned in register A. Otherwise a Q0@H value is returned, 


KRAEKKEEKKKEKEKKKEKEKKEEKEKKEKKKEKKKRKRKKKKKKEKK 


* * 
* FUNCTION 12: RETURN VERSION NUMBER * 
* * 
RREKKKKEKEKEKKKEKEKEKKEKKEKEKEKKKEKKKKKKKREKSE 
x Entry Parameters: " 
- Register Ct ~@CH * 
* * 
* Returned Value: im 
i Registers HL: Version Number * 
KEKEKKKEKEKKKEKKEKEKEKEKEKKEKERKEKEKKKKKKKKKE 
Function 12 provides information which allows’ version 
independent programming. A two-byte value is returned, with H = 068 


designating the CP/M release (H = @1 for MP/M), and L = @@ for all 
releases previous to 2.90. CP/M 2.0 returns a hexadecimal 28 in 
register L, with subsequent version 2 releases in the hexadecimal 
range 21, 22, through 2F, Using function 12, for example, you can 
write application programs which provide both seguential and random 
access functions, with random access disabled when operating under 
early releases of CP/M. 
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KKEKEKKKEEKKKEKKKEKKKREKRKKEEKKKKRKRKKKRKRKKKREKK 


* * 
* FUNCTION 13: RESET DISK SYSTEM . 
LLRERERAR EERE ASAE Dede ERAS ee aS 
* Entry Parameters: : 
* Register C: @DH 3 
* * 


KREAEKKEKKKKEKKKKKEKEKKKKEKKEKKKEKKKKKKEKKKEKKKKKK 


The Reset Disk Function is used to programmatically restore the 
file system to a reset state where all disks are set to read/write 
(see functions 28 and 29), only disk drive A is selected, and the 
default DMA address is reset to BOOT+@08@H. This function can be 
used, for example, by an application program which requires a disk 
Change without a system reboot, 


KEKKKKKKKKEKKEEKKEKEKKKEKEKEKEKKERKKEKRERKKEKREKE 


* * 
x FUNCTION 14: SELECT DISK . 
* x 
KREEKKKEKKEKKEKKRKEKEKEKKRREKEKKEEKKEKKKEKEKKKEKEKE 
* Entry Parameters: - 
x Register Cs: EH " 
2 Register E: Selected Disk * 
* # 


KEKKKKEKKKEKKEKRKEKRKKEKKREKRKKEKREKKEKRKKEKKKEKEKE 


The Select Disk function designates the disk drive named in 
register E as the default disk for subsequent file operations, with E 
= © for drive A, 1 for drive B, and so-forth through 15 corresponding 
to drive P ina full sixteen drive system. The drive is placed in an 
“on-line” status which, in particular, activates its directory until 
the next cold start, warm start, or disk system reset operation, If 
the disk media is changed while it is on-line, the drive automatically 
goes to a read/fonly status in a standard CP/M environment (see 
Function 28). FCB's which specify drive code zero (dr = @@H) 
automatically reference the currently selected default drive. Drive 
code values between 1 and 16, however, ignore the selected default 
drive and directly reference drives A through P,. 
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KRKEKKKKKKKKKKKKKKKKKEKKEKKKKKEKKEKKKKKKEK 
mn * 


* FUNCTION 15: OPEN FILE . 
x x 


RREKKKKKKKKKEKEKKEKKKEKKEKKEKKEKKKKEKKKKKKKKKK 


Entry Parameters: ? 
Register C: @FH 
Registers DE: FCB Address 


Register A: Directory Code 


* 
* 
* 
* 
* 
* 
KREEKKKKKKKKKEKRKEKEKKEKKEKEKKKEKKEKKKEKRKKKKKESE 


* 
* 
* 
Returned Value: : 
* 
® 


The Open File operation is used to activate a file which 
currently exists in the disk directory for the currently active user 
number, The FDOS scans the referenced disk directory for a match in 
positions 1 through 14 of the FCB referenced by DE (byte sl is 
automatically zeroed), where an ASCII question mark (3FH) matches any 
directory character in any of these positions. Normally, no question 
marks are included and, further, bytes "ex" and "s2" of the FCB are 
zero, 


If a directory element is matched, the relevant directory 
information is copied into bytes d@ through dn of the FCB, thus 
allowing access to the files through subsequent read and write 
operations. Note that an existing file must not be accessed until a 
sucessful open operation is completed. Upon return, the open function 
returns a “directory code" with the value @# through 3 if the open was 
Successful, or @FFH (255 decimal) if the file cannot be found. If 
question marks occur in the FCB then the first matching FCB is 
activated. Note that the current record ("cr") must be zeroed by the 
program if the file is to be accessed sequentially from the first 
record, 
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KREKKKKEKKKKKKEKKEKKEKEEKEKKEKKKKKEKKEKKKKKKKEKEKKE 


* * 
* FUNCTION 16: CLOSE FILE ” 
* * 
KREEKKKKEKKKKKEKKEKRKEKKEEKKEKEKRKKKKKRKKKRKRKKRKEKE 
* Entry Parameters: mK 
- Register C: 10H > 
sd Registers DE: FCB Address : 
* * 
* Returned Value: . 
* Register A: Directory Code * 
KKEEKKKEKKEKKEKKKKKEKKEKRKKRKKRKKKKKAKKRKRKRKKRKERE 


The Close File function performs the inverse of the open file 
function, Given that the FCB addressed by DE has been previously 
activated through an open or make function (see functions 15 and 22), 
the close function permanently records the new FCB in the referenced 
disk directory. The FCB matching process for the close is identical 
to the open function. The directory code returned for a successful 
close operation is @, 1, 2, or 3, while a ‘®@FFH (255 decimal) is 
returned if the file name cannot be found in the directory. A file 
need not be closed if only read operations have taken place, If write 
operations have occurred, however, the close operation is necessary to 
permanently record the new directory information. 
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REKEKKKEKKEKKKRKKKRKREKEKKEKKEKREKKKEKEREKRRKEKESR 
ele * 
* FUNCTION 17: SEARCH FOR FIRST * 
ole * 
KREKEKEKKKKKKKKERKEKKEKERKKKKEKKKRKEKKKKEKRKKRKRKKRKKSE 


* Entry Parameters: 
Register Cy) 28 
Registers DE: FCB Address 


Register A: Directory Code 


* 
* 
a 
* 
* 
* 
KREKKKKEKKKEKKKKEKKKKKKKKEKKKKERKKKKKRKKRKKKEEK 


* 
* 
* 
* Returned Value: 
* 
* 


Search First scans the directory for a match with the file given 
by the FCB addressed by DE. The value 255 (hexadecimal FF) is 
returned if the file is not found, otherwise 0, 1, 2, or 3 is returned 
indicating the file is present. In the case that the file is found, 
the current DMA address is filled with the record containing the 
directory entry, and the relative starting position is A * 32 (i.e., 
rotate the A register left 5 bits, or ADD A five times). Although not 
normally reguired for application programs, the directory information 
can be extracted from the buffer at this position, 


An ASCII question mark (63 decimal, 3F hexadecimal) in any 
position from "fl" through "ex" matches the corresponding field of any 
directory entry on the default or auto-selected disk drive. If the 
“dr" field contains an ASCII question mark, then the auto disk select 
function is disabled, the default disk is searched, with the search 
function returning any matched entry, allocated or free, belonging to 
any user number. This latter function is not normally used by 
application programs, but does allow complete flexibility to scan all 
current directory values. If the "dr" field is not a question mark, 
the "s2" byte is automatically zeroed. 


KHEKKEKKKKEKKEKKEKKKKKEKEKKEKKEKKKEKKKKKKKEKKEKEKEK 


* * 
* FUNCTION 18: SEARCH FOR NEXT ¥ 
x * 


KHEKKKKKKKEKKEKKKEKKEKKEKEEKEKKEKKEKKKKKKKKKKKE 


* Entry Parameters: “ 
Register C: 12H 


* * 
* * 
* Returned Value: * 
“ Register A: Directory Code * 
KHEEKKEKKEKKEKKKKEKKEKKKKEKRKEKEKEKKEKKRKRKKRKKESR 


The Search Next function is similar to the Search First 
function, except that the directory scan continues from the last 
matched entry. Similar to function 17, function 18 returns’ the 
decimal value 255 in A when no more directory items match. 
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KREKEKEKKEKEKKKKEKKKEKRKKKEKKEKERKEKKEKEKKKEKEEKKEEKE 


* * 
* FUNCTION 19: DELETE FILE id 
* * 
RKEKEKEKRKKKKKKKEKEKKEKKKRKEKRKEKKKEKRKKKKRKRKRKRRKKEKE 
* Entry Parameters: % 


Register C: 13H 
Registers DE: FCB Address 


Register A: Directory Code 


* 
* 
* 
* 
* 
KRHEAKKKKKKKKKEKKKEKKKKKEKKKEKKKKKKRKKKRKKKKEKRKEK 


* 
* 
* 
is Returned Value: 
* 


Tne Delete File function removes files which match the FCB 
addressed by DkE. The filename and type may contain ambiguous 
references (i.e., question marks in various positions), but the drive 
select code cannot be ambiguous, as in the Search and Search Next 
functions. 


Function 19 returns a decimal 255 if the referenced file or 


files cannot be found, otherwise a value inthe range @ to 3 is 
returned. 


KREKKKKKKKKEKKEKKKKKKEKKKKKKKKKKKKKKRKKKKKE 


* * 
* FUNCTION 2@: READ SEQUENTIAL * 
* * 
RKEKEKKKEKKKKEKKKEKKKKKEKEKKEKKKKKEKKKKKRKKKKKEEEK 
* Entry Parameters: ig 
* Register C: 14K * 
. Registers DE: FCB Address * 
* * 
* Returned Value: ? 
* Register A: Directory Code * 
KAKEKKKKEKKEKEKKEKKKKKKEKKKEKKKKKEKKKKKKKKKKKE 


Given that the FCB addressed by DE has been activated through an 
open or make function (numbers 15 and 22), the Read Sequential 
function reads the next 128 byte record from the file into memory at 
the current DMA address. the record is read from position "cr" of the 
extent, and the “cr” field is automatically incremented to the next 
record position, If the “cr" field overflows then the next logical 
extent is automatically opened and the "cr" field is reset to zero in 
preparation for the next read operation, The value @@H is returned in 
the A register if the read operation was successful, while a non-zero 
value is returned if no data exists at the next record position (e.g., 
end of file occurs). 
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RREEKKKEKEKKEKKEKKKEKKEKKEKKEKKKKEKKKKKKKKKKKKEKE 


* * 
* FUNCTION 21: WRITE SEQUENTIAL * 
* * 
f ' BEKKKEKKKKKEKKEEKRKEKEEKKEKRKEKKEKKEKKKKKKKKKEE 
* Entry Parameters: = 


Register Cx. 15h 
Registers DE: FCB Address 


Register A: Directory Code 


* 
* 
* 
* 
* 
KHEKEKEKEKKKEKRKEKEKKEKEKKKKEKEKEKKEEKEKKKEKEKKKRKEKKK 


* 
* 
* 
* Returned Value: 
* 
* 


Given that the FCb addressed by DE has been activated through an 
Open Or make function (numbers 15 and 22), the Write Seguential | 
function writes the 128 byte data record at the current DMA address to | 
the file named by the FCB, the record is placed at position "cr" of | 
the file, and the "cr" field is automatically incremented to the next | 
record position, If the "cr" field overflows then the next logical | 
extent is automatically opened and the “cr" field is reset to zero in | 
preparation for the next write operation, Write operations can take 
place into an existing file, in which case newly written records 
overlay those which already exist in the file. Register A = @0H upon 
return from a succesSful write operation, while a non-zero value 
indicates an unsuccessful write due to a full disk. 


KREKKKKKKKKKKEKKKKKKKKKKKKKEKKEKKKEKKEKKKKKKS | 


frn~, x ke | 
* FUNCTION 22: MAKE FILE x | 
* * 
KREEKKKEKKKEKKEKEKKKEKEKEKKEKKEKKKEKKRKKKKKKRKEKKK | 
* Entry Parameters: gi | 


Register Ces L6H 
Registers DE: FCB Address 


Register A: Directory Code 


* 
x 
* 
* 
* 
KRAEKEKEKEKEKEKKEKKKEKKKKKKKEKKKKKKKKKKKKKKKKKKK 


* 
* 
* 
* Returned Value: 
* 
* 


The Make File operation is similar to the open file operation | 
except that the FCB must name a file which does not exist in the 
currently referenced disk directory (i.e., the one named explicitly by | 
a non-zero "dr“ code, or the default disk if "dr“ is zero). The FDOS 
creates the file and initializes both the directory and main memory | 
value to an empty file. The programmer must ensure that no duplicate 
File names occur, anda preceding delete operation is sufficient if | 
there is any possibility of duplication. Upon return, register A = @, | 
1, 2, or 3 if the operation was successful and @FFH (255 decimal) if 
no more directory space is available, The make function has the 
side-effect of activating the FCB and thus a subsequent open is not 


necessary. 
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ee 


RAEEKEKKEKKKKKEKEKEKEKKEKKKKKKKKKKKKRKKKKKKKKRKEK 


* * 
* FUNCTION 23: RENAME FILE = 
* * 
KKEEKKKKEKKKKKKEKKKKKKEKKEKKKEKKKEKKKKKKEKEEKSE 
* Entry Parameters: e 
- Register Cr 178 * 
* Registers DE: FCB Address x 
* * 
* Returned Value: - 
* Register A: Directory Code * 
KEKKEKKKKEKKKKKEKKKKKKEKKEKEKKKRKKKEKKKKKKKKKEKE 


The Rename function uses the FCB addressed by DE to change all 
occurrences of the file named in the first 16 bytes to the file named 
in the second 16 bytes, The drive code "dr" at position @ is used to 
select the drive, while the drive code for the new file name at 
position 16 of the FCB is assumed to be zero. Upon return, register A 
1s set to a value between @ and 3 if the rename was successful, and 


OFFH (255 decimal) if the first file name could not be found in the 
directory scan, 


KHKKEKKKEKKKKEKKKKKEKKKKKKKKKKKKKKKKKKKKKKKE 


* * 
* FUNCTION 24: RETURN LOGIN VECTOR * 
* * 
KEKKKKKKKKKKKEKKKEKKKKEKKEKKEKEKKKKKKKRKKKEE 
x Entry Parameters: : 
" Register Cee i3u " 
* * 
* Returned Value: . 
i Registers HL: Login Vector . 
KREEKEKKEKKKEKKEKRKEKEKRKKEKKEKRKEKKKRKKKKRKKRKKKKEKE 


The login vector value returned by CP/M is a 16-bit value in HL, 
where the least significant bit of L corresponds to the first drive A, 
and the high order bit of H corresponds to the sixteenth drive, 
labelled P. A "@" bit indicates that the drive is not on-line, while 
a “1l" bit marks an drive that is actively on-line due to an explicit 
disk drive selection, or an implicit drive select caused by a file 
operation which specified a non-zero "dr" field, Note that 
compatibility is maintained with earlier releases, since registers A 
and L contain the same values upon return. 
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KREEKKKKKKEKKEKKKKEKEKKKKKKKKKAKKKKRKRKKKKKKKKEE 


* * 
* FUNCTION 25: RETURN CURRENT DISK * 
in * * 
RKEKEKEKKKEKKKKKKEKEKKKEKKEKRKKEKKEKKKKKKEKKKEKKE 
* Entry Parameters: i 
- Register Cy 298 = 
* * 
* Returned Value: - 
n Register A: Current Disk * 
KHEKKEKEKKEKKKEKEKKERKEKKEKEKKEKKKRKRKRKRKRKKKEKK KKK 


Function 25 returns the currently selected default disk number 


in register A, The disk numbers range from @ through 15 corresponding 
to drives A through P. 


KHKEKKKKEKKKEKKEKREKKEKEKEKEKRKKEKEKKREKKKEKKKREKE 


* # 
* FUNCTION 26: SET DMA ADDRESS : 
* 
KAEKKKKKEKKKKKEKKKKEKKKEKEKEKKKKKKKKKKKKKKEKEE 
x Entry Parameters: * 
* Register C: 1AH - 
if Registers DE: DMA Address 
* * 

c™ KREKEKKEKKKEKKEKKEKEKKEKKKKKEKKEKKKKKKKRKEKKKKKEKE 

“DMA" is an acronym for Direct Memory Address, which is’ often 

used in connection with disk controllers which directly access the 
memory of the mainframe computer to transfer data to and from the disk 
Subsystem. Although many computer systems use non-DMA access (1.ée., 
the data is transfered through programmed I/O operations), the DMA 
address has, in CP/M, come to mean the address at which the 128 byte 
data record resides before a disk write and after a disk read. Upon 
cold start, warm start, or disk system reset, the DMA address is 
automatically set to BOOT+#080H. The Set DMA function, however, can 
be used to change this default value to address another area of memory 
where the data records reside. Thus, the DMA address becomes’ the 
value specified by DE until it is changed by a subsequent Set DMA 
function, cold start, warm start, or disk system reset, 

c~ 
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KREEKKKEKEKKEKKKKEKEKKEKEKEKKEKKKEKKEKKEKKEKE 


* * 
* FUNCTION 27: GET ADDR (ALLOC) * 
* * 
KKKKKK KKK KKK KRKKKKKEKRKKEKKEKEKKERKKKKKKKK py 
* Entry Parameters: ss 
= Register Cs: 1BH m 
* * 
* Returned Value: 
. Registers HL: ALLOC Address * 
KRKEKKKKEKKKKKKKRKEKKKRKKEKRKKKEKEKEKKKEKRKEKKKKEKESE 


An “allocation vector" is maintained in main memory for each 
On-line disk drive. Various system programs use the information 
provided by the allocation vector to determine the amount of remaining 
storage (see the STAT program). Function 27 returns the base address 
of the allocation vector for the currently selected disk drive. The 
allocation information may, however, be invalid if the selected disk 
has been marked read/only. Although this function is not normally 


used by application programs, additional details of the allocation 
vector are found in the "CP/M Alteration Guide," 


KREKEKKEKKKKEKKKEEKKEKKKKEKEEKKKKEKKKEKEKKKEKKESE 
* * 


* FUNCTION 28: WRITE PROTECT DISK : 
* 


KKEEKEKKKEKEKEKEKKEKKKEKKEKEKKKERKEKEKKKEKKKEKKKEKKKE 


* Entry Parameters: " 
¥ Register Ce CH * 
* * 


KKKEKKKKEKKEKKEKKKEKKKEKKEKKKEKKKKKKKEKKKEKKKKRES 


The disk write protect function provides temporary write 
protection for the currently selected disk. Any attempt to write to 
the disk, before the next cold or warm start operation produces the 
message 


Bdos Err on d: R/O 
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KHEKEKKKKKKKKEKEKKKEKKEKEEEKKKEKKKEKEKRKEEKRE 
* * 


* FUNCTION 29: GET READ/ONLY VECTOR * 
* x 


KEKKEKKEKKEKEKKKEKRKEKKKKEKKEKKKKKKKKKKKRKKKKK 


* Entry Parameters: m 
ie Register ce Ip = 
* * 
* Returned Value: sd 
* Registers HL: R/O Vector Value* 
KREKKKKKEKKEKEKRKEKRKEKRKEKREKRKKEKKEKRKKRKKRKKRKRKKKEEK 


Function 29 returns a bit vector in register pair HL which 
indicates drives which have the temporary read/only bit set. Similar 
to function 24, the least sianificant bit corresponds to drive A, 
while the most significant bit corresponds to drive P. The R/O bit is 
set either by an explicit call to function 28, or by the automatic 
software mechanisms within CP/M which detect changed disks. 


KEKEKEKKKKKKEKEKKEKKKEKKEEKKKKEKEKKEKKEEKKKKKKEKK 
* * 


* FUNCTION 36: SET FILE ATTRIBUTES . 
x x 


KKEEKKKEKEKKKEKKEKEKEKEKKKKKKEKKKKKKKKKKKKEKKKKKE 


* Entry Parameters: . 
ud Register Cs.-eslise * 
i) Registers DE: FCB Address * 
* * 
* Returned Value: " 
z Register A: Directory Code * 
KEKEKKKKEKKEKKEKKKEKKKEKEKEKRKEEKKEKKEKEKKKEKK 

The Set File Attributes function allows programmatic 
manipulation of permanent indicators attached to files. In 
particular, the R/O and System attributes (tl' and t2') can be set or 
reset, The DE pair addresses an unambiguous file name with the 
appropriate attributes set or reset. Function 38 searches for a 
match, and changes the matched directory entry to contain the selected 
indicators. Indicators fl’ through £4° are not presently used, but 


may be useful for applications programs, since they are not involved 
in the matching process during file open and close operations. 


Indicators £5' through £8' and t3' are reserved for future system 
expansion, 
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KKEEKKKKEKKEKKEKKKEKKEKKKKKKEKRKRKKKKKKKERKKKKE 
oe * 
* FUNCTION 31: GET ADDR(DISK PARMS) * 
* * 
KREKEKEKKEKKKEKKKEKKKRKKERKKRKEKRKRKERKKEKKKEE 


* Entry Parameters: 
Register Ce FH 


* 
* 
* Returned Value: 
* 
* 


Registers HL: DPB Address 
KKEKEKKEKKKKEKKKEKEKEKKKRKEKKEKKKKERKKKRERKEKK 


* 
* 
* 
* 
* 
* 

The address of the BIOS resident disk parameter block is 
returned in HL as a result of this function call. This address can be 
used for either of two purposes, First, the disk parameter values can 
be extracted for display and space computation purposes, or transient 
programs can dynamically change the values of current disk parameters 
when the disk environment changes, if required. Normally, application 
programs will not require this facility. 


KEKEKEKKKKKKKKKKKKKEKKKKEKEKKKEKRKEKKEKKKKRKRKKKE 


x * 
* FUNCTION 32: SET/GET USER CODE * 
* * 
KRREKEKKKEKKKKEKKKKEKKKKKKKKRKKRKKKRKKKKKRKKRKRKKE 
* Entry Parameters: “ 
i Register C: 20H m 
Z Register E: @OFFH (get) or ee 
= User Code (set) * 
4 * 
* Returned Value: = 
* Register A: Current Code or * 
‘ (no value) 
REKKKKKKKEKKEKKKKKKKKRKKRKKKRKKKKKKKKRKRKRKKEKSE 


An application program can change or interrogate the currently 
active user number by calling function 32. If register E = @FFH, then 
the value of the current user number is returned in register A, where 
the value is in the range @ to 3l. If register E is not @FFH, then 
the current user number is changed to the value of E (modulo 32). 
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KREEKKKKEKEKEKKKKKKKKKEKKKKKKKKKKKKKRKKKKKEKKE 








oe * 
* FUNCTION 33: READ RANDOM : | 
KREKKKKKKKKKEKKKEKKEKKEKKKEKKKEKEKKEKKKKKKKKKEE | 
* Entry Parameters: * | 
* Register C: 21H = | 
* Registers DE: FCB Address = 
* * 
* Returned Value: _ 
- Register A: Return Code = 
KEAEKKKKKEKKKKKKEKKKEEKKKKKKEKKKKEKKKKKKKRKRKKEK 


The Read Random function is similar to the sequential file read 
operation of previous releases, except that the read operation takes 
place at a particular record number, selected by the 24-bit value 
constructed from the three byte field following the FCB (byte 
positions r@ at 33, rl at 34, and r2 at 35). Note that the sequence 
of 24 bits is stored with least significant byte first (r@), middle 
byte next (rl), and high byte last (r2). CP/M does not reference byte 
r2, except in computing the size of a file (function 35). Byte r2 
must be zero, however, since a non-zero value indicates overflow past 
the end of file. 





Thus, the r@,rl byte pair is treated as a double-byte, or "word" 
value, which contains the record to read. This value ranges from @ to | 
65535, providing access to any particular record of the 8 megabyte | 
File. In order to process a file using random access, the base extent | 

a (extent 8) must first be opened. Although the base extent may or may 

| not contain any allocated data, this ensures that the file is properly 
recorded in the directory, and is visible in DIR reguests. The 
selected record number is’ then stored into the random record field 
(r@,rl), and the BDOS is called to read the record. Upon return from 
the call, register A either contains an error code, as listed below, 
or the value 0@ indicating the operation was successful. In the 
latter case, the current DMA address contains the randomly accessed 
record. Note that contrary to the sequential read operation, the 
record number iS not advanced, Thus, Subsequent random read 
operations continue to read the same record. 





(EOE EEOoOooE———————— —— 


Upon each random read operation, the logical extent and current 
record values are automatically set, Thus, the file can be 
sequentially read or written, starting from the current randomly 
accessed position, Note, however, that in thiS case, the last 
randomly read record will be re-read as you switch from random mode to 
sequential read, and the last record will be re-written as you switch 
to a sequential write operation. You can, of course, simply advance 
the random record position following each random read or write to 
obtain the effect of a sequential I/O operation, 


Error codes returned in register A following a random read are 
listed below. 
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G1 reading unwritten data 

62 (not returned in random mode) 
03 cannot close current extent 

94 seek to unwritten extent 

05 (not returned in read mode) 

96 seek past physical end of disk 


Error code @1 and @4 occur when a random read operation accesses a 
data block which has not been previously written, or an extent which 
has not been created, which are equivalent conditions, Error 3 does 
not normally occur under proper system operation, but can be cleared 
by simply re-reading, or re-opening extent zero as long as the disk is 
not physically write protected, Error code 96 occurs whenever byte r2 
is non-zero under the current 2.9 release, Normally, non-zero return 
codes can be treated as missing data, with zero return codes 
indicating operation complete, 
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REKKKKKKKKKKKKKKKKKKKKKKKKKRKKKKKKKKKRKEKK 


* * 
* FUNCTION 34: WRITE RANDOM : 
se * 
KHEEKEKHRKRKKEEKEKEKEKEKRKKKRKKKRKKRKKRKKEKKRKKESR 
* Entry Parameters: = 
* Register C: 22H . 
% Registers DE: FCB Address = 
* * 
* Returned Value: 
* Register A: Return Code . 
KHEEKKEKEKKEKKEEKKEKKKEKKKKEKKKKKRKRKKKRKKKKEKKKKK 


The Write Random operation is initiated similar to the Read 
Random call, except that data is written to the disk from the current 
DMA address. Further, if the disk extent or data block which is’ the 
target of the write has not yet been allocated, the allocation is 
performed before the write operation continues, As in the Read Random 
operation, the random record number is not changed as a result of the 


write, The logical extent number and current record positions of the 
file control block are set to correspond to the random record which is 
being written, Again, sequential read or write operations can 


commence following a random write, with the notation that the 
currently addressed record is either read or rewritten again as_ the 
sequential operation begins. You can also simply advance the random 
record position following each write to get the effect of a seguential 
write operation, Note that in particular, reading or writing the last 
record of an extent in random mode does not cause an automatic extent 
Switch as it does in sequential mode, 


The error codes returned by a random write are identical to the 
random read operation with the addition of error code @5, which 
indicates that a new extent cannot be created due to directory 
overflow. 
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RREKEKKKKKEKKKKKKKEKEKKKEKKKEKKKKKKKKKKKRKKRKEKE 
* * 


* FUNCTION 35: COMPUTE FILE SIZE * 
* 


* 
KREKEKKKKKKRKEKKKEKEKKKEKKEKEEKREKRKREKRKKEKEKKKKKKESE 


* Entry Parameters: 
Register CH. -238 
Registers DE: FCB Address 


Random Record Field Set 


x 
* 
ry 
* 
* 
* 
KKEKKKKEKKKKEKKKEKEKKEKEKKEKREKRKEKEREKRKKEKRRKEKKKESE 


* 
* 
* 
* Returned Value: 
* 
* 


When computing the size of a file, the DE register pair 
addresses an FCB in random mode format (bytes r@, rl, and r2 are 
present). The FCB contains an unambiguous file name which is used in 
the directory scan. Upon return, the random record bytes contain the 
"virtual" file size which is, in effect, the record address of the 
record following the end of the file. if, following a call to 
function 35, the high record byte r2 is 01, then the file contains the 
maximum record count 65536. Otherwise, bytes r@ and rl constitute a 
lo-bit value (r@ is the least significant byte, as before) which is 
the file size. 


Data can be appended to the end of an existing file by simply 
calling function 35 to set the random record position to the end of 
file, then performing a sequence of random writes starting at the 
preset record address, 


The virtual size of a file corresponds to the physical size when 
the file is written sequentially. If, instead, the file was created 
in random mode and “holes" exist in the allocation, then the file may 
in fact contain fewer records than the size indicates, It, ¢.2OL 
example, only the last record of an eight megabyte file is written in 
random mode (1.e., record number 65535), then the virtual size is 
65536 records, although only one block of data is actually allocated. 
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REEKEKKKKKRKKEKEKEKKEKKKKKEKKRKKRKKRKKRKKEKKKEKRKEKESE 
on * 
f™» * FUNCTION 36: SET RANDOM RECORD * 
* * 
KRREKEKKKEKKKKEKKEKKKKEKEKKEKRKKEKKKKKKKKKKKEEKSE 


* Entry Parameters: 
Register Cs: 24H 
Registers DE: FCB Address 


Returned Value: 


Random Record Field Set 


* 
* 
* 
* 
* 
KEKKKKEKEKKKKKKKKEKRKERRRKKKKEKKKKK RRR KKEKK 


* 
* 
* 
* 
* 
* 
* 


The Set Random Record function causes the BDOS to automatically 
produce the random record position from a file which has been read or 


written seguentially to a particular point. The function can be 
useful in two ways. 


First, it is often necessary to initially read and scan a 
sequential file to extract the positions of various "key" fields. As 
each key is encountered, function 36 is called to compute the random 
record position for the data corresponding to this key. If the data 
unit size is 128 bytes, the resulting record position is placed into a 
table with the key for later retrieval. After scanning the entire 
file and tabularizing the keys and their record numbers, you can move 
instantly to a particular keyed record by performing a random read 
uSing the corresponding random record number which was saved earlier, 

loa The scheme is eaSily generalized when variable record lengths are 
involved since the program need only store the buffer-relative byte 
position along with the key and record number in order to find the 
exact starting position of the keyed data at a later time. 


A second use of function 36 occurs when switching from a 
sequential read or write over to random read or write. A file is 
sequentially accessed to a particular point in the file, function 36 
is called which sets thé record number, and subsequent random read and 
write operations continue from the selected point in the file. 
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3. A SAMPLE FILE-TO-FILE COPY PROGRAM, 


The program shown below provides a relatively simple example of 
File operations. The program source file is created as COPY.ASM using 
the CP/M ED program and then assembled using ASM or MAC, resulting in 
a “HEX" file. The LOAD program is the used to produce a COPY.COM file 
which executes directly under the CCP. The program begins by setting 
the stack pointer to a local area, and then proceeds to move the 
second name from the default area at @®@6CH to a 33-byte file control 
block called DFCB. The DFCB is then prepared for file operations by 
clearing the current record field. At this point, the source and 
destination FCB's are ready for processing since the SFCB at @@5CH is 
properly set-up by the CCP upon entry to the COPY program. That is, 
the first name is placed into the default fcb, with the proper fields 
zeroed, including the current record field at @@7CH. The program 
continues by opening the source file, deleting any exising destination 
file, and then creating the destination file. If all this is 
successful, the program loops at the label COPY until each record has 
been read from the source file and placed into the destination file. 
Upon completion of the data transfer, the destination file is closed 
and the program returns to the CCP command level by jumping to BOOT. 


sample file-to-file copy program 
at the ccp level, the command 
copy a:x.y b:u.v 


copies the file named x.y from drive 
a to a file named u.v on drive b. 


oe we We VO =e we TO BO WO 


G009 = boot equ 090 0h ; system reboot 
9205 = bdos equ 0085h > bdos entry point 
@G5c = fcbl equ 085ch - first file name 
GG5c = sfcb equ Ecbl ; source fcb 

@B6c = fcb2 equ @%6ch ; second file name 
0080 = dbuff equ 0880h >; default buffer 
0190 = tpa equ G188h ; beginning of tpa 
$009 = printf egu 9 > print buffer func# 
QOGE = openf equ 15 > open file func# 
9019 = closef equ 16 ; close file func# 
9213 = deletef egu 19 > delete file func# 
9914 = readf equ 20 > seguential read 
0615 = writef equ 21 > sequential write 
9016 = makef equ 22 > make file func# 
B1BG Org tpa * beginning of tpa 
9100 311b02 1x1 sp,stack; local stack 


—™e ~e 


move second file name to dfcb 


9103 Gel® mMv1 c,16 « half an fcb 
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0195 116c0O 1x1 aqg,fcb2 ;: source of move 
9198 21ldagvl 1x1 h,dfcb ; destination fcb 
0910b la mfcbs ldax d * source fcb 
910@c 13 inx d - ready next 
10d 77 mov m,a > dest fcb 
Gl1lve 23 1nx h ; ready next 
@10£ Bd dcr c + COUNT 6.1.8 
9119 c20bd1 jnz mfcb ; loop 16 times 
° name has been moved, zero cr 
9113 af xra a > a = 00h 
9114 32faGl sta dfcbhcr ; current rec = Q@ 
source and destination fcb's ready 
9117 115c0O 1x1 d,sfcb ; source file 
Glla cd6961 call open ~error: 1f 255 
Olid 118761 1xi d,nofile; ready message 
8128 3c ine a * 255 becomes @ 
$121 cc61@1 CZ finis * done if no file 
; source file open, prep destination 
9124 lidagl 1xi qd,dfcb ; destination 
9127 cd7361 call delete ; remove if present 
G@l2a lldagl 1xi qd,afcb ; destination 
G1l2d cd8201 call make * create the file 
9130 1196901 1x1 d,nodir ; ready message 
9133) 3¢ inr a * 255 becomes @ 
9134 cc6ldgl cz finis ; done if no dir space 
; Source file open, aest file open 
; copy until end of file on source 
0137 115c0@ copy: 1x1 a,sfcb ; source 
G9l3a cd7/780l call read -; read next record 
G13d b7 ora a end of file? 
Gl3e c25191 jnz eofile ; skiv write if so 
° not end of file, write the record 
0141 lidagl 1x1 d,dfcb ; destination 
9144 cd7d@l call write * write record 
0147 11a9@1 1lxi d,space ; ready message 
914a b7 ora a - ©@ 1£ write ok 
Gl4b c46191 cnz finis * end if so 
014e c33701 jmp copy ; loop until eof 
eofile: ; end of file, close destination 
6151 lidagl 1x1 qd,dfcb ; destination 
6154 cd6e@1 call close °° 255 1f error 
9157 21lbb61 1x1 h,wrprot; ready message 
G@l5a 3c nr a * 255 becomes 0@ 
915b cc6101 CZ finis ; shouldn't happen 
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015e llcc@l 1x1 d,normal; ready message 


finis: ; write message given by de, reboot 


$161 B8eG9 mvi CS PELLICLE 
0163 cdd5020 call bdos ; write message 
9166 c30000 J mp boot ; reboot system 


system interface subroutines 
(all return directly from bdos) 


O —=~e ~O *O VE 


9169 edt pen: mv c,opent 
Q16b c38500 J mp bdos 
Globe geld close: mvi c,closef 
0178 c38506 J mp bdos 
0173 bel3 delete: mvi c,deletef 
0175 c30580 jmp bdos 
9178 gel4 read: mvi c,readf 
Gl7a c30500 J mp bdos 
Q17d ®el5 write: mvi c,writef 
G17£ c30500 jmp bdos 
0182 Gel6 make: mvi c,makef 
9184 c30580 jmp bdos 
:, console messages 
0187 be6f£2Wfnofile: db ‘no source files’ 
W196 6e6f209nodir: db ‘no directory spaces’ 
Ola9 6£7574fspace: db ‘out of data space$s' 
Olbb 7772695wrprot: db ‘write protected?$' 
Jlcc 636f£70G@normal: db ‘copy completes’ 
: data areas 
Glda GEcbs ds 33 * destination fcb 
Olfa = aqfcbcr equ dfcb+32 3; current record 
O1f£b as 32 ; 16 level stack 
Stack: 
021b end 


Note that there are several simplifications in this particular 
program, First, there are no checks for invalid file names which 
could, for example, contain ambiaquous' references, This situation 
could be detected by scanning the 32 byte default area starting at 
location @@5CH for ASCII question marks. A check should also be made 
to enSure that the file names have, in fact, been included (check 
locations @@5DH and ®@6DH for non-blank ASCII characters). Finally, a 
check should be made to ensure that the source and destination file 
names are different. A speed improvement could be made by buffering 
more data on each read operation, One could, for example, determine 
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the size of memory by fetching FBASE from location 0096H and use the 
entire remaining portion of memory for a data buffer. In this case, 
the programmer simply resets the DMA address to the next successive 
128 byte area before each read. Upon writing to the destination file, 
the DMA address is reset to the beginning of the buffer and 
incremented by 128 bytes to the end as each record is transferred to 
the destination file. 
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4, A SAMPLE FILE DUMP UTILITY, 


The file dump program shown below is slightly more complex than 
the simple copy program given in the previous section. The dump 
program reads an input file, specified in the CCP command line, and 


displays the content of each record in hexadecimal format at the 
console, Note that the dump program saves the CCP's stack upon entry, 
resets the stack to a local area, and restores the CCP's stack before 
returning directly to the CCP. Thus, the dump program does not 
perform and warm start at the ena of processing. 


; DUMP program reads input file and displays hex data 


e 
a 


G19 org 166h 
W005 = bdos equ 09@@5h ;dos entry point 
OG0l = cons edu f/ sread console 
G0G2 = typef equ 2 stype function 
9609 = printf equ g ;buffer print entry 
G00b = brkf equ ciel ;break key function (true if char 
O@0f = openf equ i >file open 
9014 = readf equ 20 ;read function 
G05c = feb equ 5ch ;file control block address 
QG80 = buff equ 8 @h sinput disk buffer address 
non graphic characters 
008d = “on equ Och ;Carriage return 
00Ga = 1f equ Gah ;line feed 
: file control block definitions 
@W5c = tcbdn equ Ecb+u ;disk name 
085d = Febrn equ fcbt+l file name 
09065 = LGBLE equ fcbt+9 ;disk file type (3 characters) 
0068 = febrl equ febtl2 ;file's current reel number 
G86b = fcbre equ feb+15 ;file's record count (@ to 128) 
GH/c = fcbcr equ feb+32 ;current (next) record number (@ 
007d = Foeola egu fcotss <<if65 bength 
° set up stack 
0109 210000 1xi h,@ 
©1083 39 dad sp 
; entry stack pointer in hl from the ccp 
9104 221582 shld oldsp 3 
. set sp to local stack area (restored at finis) 
9107 315702 1x1 sp,stktop 
; read and print successive buffers 
G91@a cdclgl call setup set up input file 
§10d feff a 255 7255 if file not present 
@18f c21b01 jnz openok ;Skip if open is ok 
° File not there, give error message and return 
G@112 11£3901 lxi d,opnmsg 
@115 cd9cOl call err 
118 c35191 jmp finis sto return 


WZ 
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O@1lb 
G1ll1d 


G120 


0123 
0124 
0127 
$128 
@12b 


Q12c 
912d 
Q12f 


@132 


G135 


0138 
9139 


G13c 
G13d 
G914@ 
9141 


9144 
@145 
9147 
014a 
@14b 
G14e 


8151 
9154 
9157 


9158 


9159 
Q@15c 
015e 
6161 
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3e80 
3213082 


2190000 


7a 
e60f 
c24461 


cd72¢01 


cd59@1 


Of 
da51@1 


cd8f£Ol 


23 
3e2¢ 
cd6501 
78 
casgftdl 
c32301 


Ca7261 
2a15@2 
£9 


cg 


e5d5c5 
Bebb 

cdé582 
Cldlel 


openok: 


me 


gloop: 


=e Oe 


=e ~™e ~O =e 


=e 


nonums 


sopen operation ok, set buffer index to end 
mvl a, 8@h 

sta ibp ;set buffer pointer to 80h 
hl contains next address to print 


1xi h,@ sstart witn @000 

push h ;save line position 

call gnb 

pop h srecall line position 

jc finis scarry set by gnb if end file 
mov b,a 


print hex values 
check for line fold 


mov a,l 

ani Ofh check low 4 bits 
jnz nonum 

print line number 

call crlf 

check for break key 

call break 

accum lsb = 1 if character ready 

rrc sinto carry 

7¢ finis ;don't print any more 
mov a,h 

call phex 

mov a,l 

call phex 

1nx h sto next line number 
mvi ayo ao 

call pchar 

mov a,b 

call phex 

J mp gloop 


end of dump, return to ccp 
(note that a jmp to @@80h reboots) 


call Sait 

lhid oldsp 

sphl 

stack pointer contains ccp's stack location 
ret sto the ccp 

subroutines 


;check break key (actually any key will do) 
push h! push d! push b; environment saved 
mv1 CpDrkt 

call bdos 

pop b! pop d! pop h; environment restored 


35 











ee a Se ee oe 


0164 c9 ret 
pehar: ;print a character 
0165 e5d5c5 push h! push d! push b; saved 
0168 BeG%2 mvi c,typef 
Gloa 5f mov e,a 
916b cd0580 call bdos 
@l6e cldlel pop b! pop d! pop h; restored 
C171 aes ret 
crlf: 
9172 3e0d mvi a,cr 
0174 cd6501 call pchar 
8177 3e@a mv1 a,lf 
9179 cd65@1 call pehar 
G@l7c c9 ret 
pnib< sprint nibble in reg a 
Q17d ebE anil fh slow 4 bits 
O1/7£ fea cpl 1@ 
0181 d289@1 Bele p1d 
: less than or egual to 9 
9184 c63@ adi ‘O° 
9186 c38bél J mp prn 
: greater or equal to 19 
0189 c637 plé@: adi ‘a’ - 10 
018b cd65@l1 prn: call pchar 
@18e c9 ret 
phex: sprint hex char in reg a 
O18f £5 push psw 
0190 Of Ere 
Q191 OF rre 
09192 Of rire 
G193 OF rrc 
0194 cd7dadl call pnib sprint nibble 
9197 f1 pop pSw 
9198 cd7d@l call pnib 
Q19b cQ9 ret 
errs: sprint error message 
; d,e addresses message ending with "Ss" 
G919c GeG9 mvl C,printt sprint buffer function 
G19e cdd500 call bdos 
®@lal c9 ret 
gnb: ;get next byte 
DlazZ 3al1302 lda 1bp 
Gla5 fe8O cpl 80h 
®la7 c2b3G1 jnz gd 
° read another buffer 
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Qlaa cdcegl call diskr 


Glad b7 ora a zero value if read ok 
Glae cab3@1 Jz gd ;for another byte 
; end of data, return with carry set for eof 
91bl 37 stc 
G@1b2 c9 ret 
ga: sread the byte at bufft+reg a 
@1b3 5£ mov e,a sls byte of buffer index 
91b4 1609 mvi d,@ sdouble precision index to de 
G1b6 3c inr a *index=index+l 
@1b7 321302 sta ibp sback to memory 
; pointer is incremented 
; save the current file address 
Glba 218000 1x1 h,buff 
Glbd 19 dad 
: absolute character address is in hl 
Glbe Je mOvV a,m 
: byte is in the accumulator 
®lbf b7 ora a sreset carry bit 
G1lcO c9 ret 
setup: ;set up file 
; open the file for input 
O1lcl af xra a *zero to accum 
Blce2 327c00 sta fcocr eclear current record 
91c5 115c0O lxi G,ico 
Q1lc8 Bef mvi c,openf 
Blca cd#500 call bdos 
H 255 in accum if open error 
Glcd c9 ret 
Giskr: ;read disk file record 
Olce e5d5c5 push h! push d! push b 
Gld1l 115c@9 1xi d,fcb 
91d4 @el14 mv1 c,readf 
Q91ld6 cdg@500 call bdos 
@1d9 cldlel pop b! pop d! pop h 
Qldc c9 ret 
; fixed message area 
Bldd 46494c@signon: db ‘file dump version 2.0$' 
Q1f3 Bdva4eHopnmsg: db cr,lf,'no input file present on disks’ 
° variable area 
9213 ibp: ds 2 sinput buffer pointer 
@215 oldsp: ds 2 sentry sp value from ccp 
: stack area 
9217 ds 64 sreserve 32 level stack 
Sstktop: 
9257 end 
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2. A SAMPLE RANDOM ACCESS PROGRAM. 


This manual is concluded with a rather extensive, but complete 
example of random access operation, The program listed below performs | 
the simple function of reading or writing random records upon command Wy 


from the terminal. Given that the program has been created, 
assembled, and placed into a file labelled RANDOM.COM, the CCP level 
command: 


RANDOM X.DAT 


starts the test program, The program looks for a file by the name 
X.DAT (in this particular case) and, if found, proceeds to prompt the 
console for input. If not found, the file is created before the 
prompt is given. Each prompt takes the form 


| next command? 


and is followed by operator input, terminated by a carriage return. 
The input commands take the form 


| nw nR QO 


where n is an integer value in the range @ to 65535, and W, R, and Q 
| are Simple command characters corresponding to random write, random 
| read, and quit processing, respectively. If the W command is’ issued, 
| the RANDOM program issues the prompt 


type data: 


The operator then responds by typing up to 127 characters, followed by = 
a carriage return. RANDOM then writes the character string into the 
X.DAT file at record ng. If the R command is issued, RANDOM reads 
record number n and displays the string value at the console. If the 

Q command is issued, the X.DAT file is closed, and the program returns 

to the console command processor. In the interest of brevity, the 

only error message is 


error, try again 


The program begins with an initialization section where the 
input file is opened or created, followed by a continuous loop at the 
label “ready" where the individual commands are interpreted. The 
default file control block at @@5CH and the default buffer at @080H 
are used in all disk operations. The utility subroutines then follow, 
which contain the principal input line processor, called "“readc." 


This particular program shows the elements of random access 
processing, and can be used as the basis for further program 
development. 
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0x * 
;* sample random access program for cp/m 2.90 - 
x * 
ETI TTT TTI T TTI TITIT TTT T TTT TTT TTT 

0100 org 109h sbase of tpa 

O000 = repoot egu 888Gh ;system reboot 

9005 = bdos equ @905h ;bdos entry point 

0001 = coninp equ 1 ;console input function 

9802 = conout egu 2 console output function 

$209 = pstring egu 9 ‘print string until *s* 

G0Va = rstring egu 190 sread console buffer 

QG0c = version equ 12 sreturn version number 

O90E = openf equ 15 file open function 

0018 = closef equ 16 close function 

9816 = makef equ 22 smake file function 

90821 = readr equ 33 sread random 

9022 = writer egu 34 ewrite random 

O05c = fcb egu 0985ch ;default file control block 

007d = ranrec equ fcb+33 ;random record position 

O@7£ = ranov£ equ fcb+35 ;high order (overflow) byte 

0080 = buff egu G080h sbuffer address 

902d = cr equ Gdh scarriage return 

G@08a = ity egu Gah sline feed 
CIO IOC IOI GIO ICICI ICICI IOI III III IO I Ie 
0x * 
;* load SP, set-up file for random access . 
o * x 
COGIC GIGI GI ICICI IOI OIG IOICIOCI ICICI II IOI IOI IE 

G@108 3l1bc@ 1xi sp,stack 
rs version 2.0? 

9103 Bebc mvl c,version 

9105 cdg@5a call bdos 

9108 fe2Q cpl 26h ;version 2.8 or better? 

G918a d216@ jnc versok 
. bad version, message and go back 

919d 111bé@ 1x1 d,badver 

9110 cddag call print 

9113 c3600 jmp reboot 
versok: 
; correct version for random access 

116 ®ebE mvl c,openf ;open default fcb 

9118 115c@ 1x1 a,fcb 

Ollb cdo5@ call bdos 

Olle 3c inr a ;err 255 becomes zero 

GL1IL e2378 jnz ready 


=e BWE 


cannot open file, so create it 
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9137 
Ql3a 
013d 
0140 
9142 
9144 


0147 
149 
G14c 
O14f 
0150 
09153 


9156 
0158 


G@15b 
915e 
8161 
8163 


6166 
0167 
0168 
016b 
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cde5a@ 
22/da@ 
217£2 
3609 
fe5l 
c256@ 


Geld 
115c@ 
cdg5@ 
3c 
cab9Qg 
c3000 


mvi1 c,makef 

1x1 d,fcb 

call bdos 

inr a serr 255 becomes zero 
jnz ready 

’ 

; cannot create file, directory full 

lxi qa,nospace 
call print 
J mp reboot ;back to ccp 

; 

e RK KKKKKKKKKEKKKKEKKKKEKKKKKKRKKKKKKKKKKEKEKKEKKKKKKKKKKKES 
* * 
* loop back to “ready” after each command * 
* * 
KEKEKEKKEKKKKEKKEKEKRREEKEREKRKEKKKEKKKEEKKREKKKRKKRKKKKRKKKEKRKEREKEK 


40) 

ey) 

QO, 
< 


file is ready for processing 


~e we FY me me TO te we 


call readcom ;read next command 

shld ranrec ;store input record# 
lxi h,ranovf 

mvi m,@ ;Clear high byte if set 
cpt oe secur? 

jnz notq 


me 6 


quit processing, close file 


mvi c,closef 

1x1 é Bb oll 2 

call bdos 

Int a serr 255 becomes @ 

jz error serror message, retry 
jmp reboot ;back to ccp 


; 
e KKK KKKKKKKEKKKEKKKEKEKKEKEKKEKKKEKKKEKKKEKKEKKKEKKKEKKKKKKKEKKE 
’ 


«x * 
7* end of quit command, process write : 
7x * 
RII OOO IGG IGI III IG IG IE 
nota: 
not the quit command, random write? 

cpl ‘Ww! 

jnz notw 
: this is a random write, fill buffer until cr 

1x1 d,datmsg 

call brant ;data prompt 

mvl Cyl? sup to 127 characters 

1a h,buff :sdestination 


rloop: ;read next character to buff 


push b *-Save counter 
push h ;next destination 
call getchr ;:character to a 
pop h restore counter 
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®1l6c cl pop b srestore next to fill 
Gl6d fed cpl cr send of line? 
O16£ ca78a jz erloop 
; not end, store character 
9172 77 mov m,a 
G173 23 inx h enext to fill 
174 0a der e scounter goes down 
09175 c266d jnz rloop send of buffer? 
erloop: 
; end of read loop, store @®@ 
G178 3600 mv1l m,@ 
: write the record to selected record number 
Ol7a Ge22 mvi c,writer 
Gl7c 115cO 1x1 d,fcb 
G17£ cdg5@ call bdos | 
@182 b7 ora a serror code zero? | 
0183 c2b9¢@ jnz error smessage if not | 
9186 c3379 jmp ready >for another record | 
SIC III ICO IG IOC ICICI III Ik | 
a . 
7;* end of write command, process read * 
ox * 
GIGI GIGI IIIS ICICI III GIGI IIIT III II ICR 
notws 
: not a write command, read record? 
0189 fe52 cpl ‘R' 
G@18b c2b9@ jnz error skip if not 2 
: read random record 
0918e We21 mvi c,readr 
G198 115c@ 1lxi d,fcb 
89193 cdd5@ call bdos 
0196 b7 ora a sreturn code @0? 
9197 c2b90 jnz error 
° read was successful, write to console 
619a cdcfd call crlf snew line | 
G@19d Ge8O mvi c,128 emax 128 characters | 
G19£ 21800 1xi h,buf£ ;s;next to get | 
wloop: | 
Qla2 Je mov a,m enext character 
Gla3 23 inx snext to get 
Bla4 e67f ani 7£h smask parity 
9la6é ca37@ jz ready s;for another command if 9@ 
G@la9 c5 push b ssave counter 
®laa e5 push h ssave next to get | 
®lab fe2@ cpi ek sgraphic? | 
Glad d4c86@ cnc putchr ;skip output if not 
Glb@ el pop h 
Glbl cl pop b 
Glb2 Od dcr c scount=count-1l 
Glb3 c2a2G jnz wloop 
G1lb6 c33790 J mp ready 
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See ee) ee ees he 


01b9 


Glbc 
@lbf 


G1lc2 
Q1lc4 
Qlc7 


G1c8 
@lca 
Qlcb 
Glce 


Ol1lcf 
G1ldl 
G1d4 
@1d6 
G1d9 


Qlda 
Bldb 
Olde 
Gldf 
Qlel 
Gle4 


Gle5 
G1les8 
Gleb 
led 
G1fd 
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’ 

ox 

’ 
* * 

’ 

’ 


;* end of read command, all errors end-up here * 
2 * * ~~ 
eR KKKKKKKEKKKKEKKKKKKEKEKKEKKKKKKKEKKKEKKKKKEEKKKEEKKKKEKKKKKE 
error 
11590 1x1 d,errmsg 
cddag call print 
C3379 J mp ready 
CRE KKKKKEKKKKKEKKEKKEKK EK KEKKKKKKEREKKKEKEKKEKKKEKKKRKKKKKKE 
ex * 
;* utility subroutines for console i/o . 
ox * 
ROO IGG IGS SI GIGI G ICG IOI ICICI TOI TOI IR 
getchr: 
;read next console character toa 
Gebl mvi c,coninp 
cdg5a call bdos 
cg ret 
putchr: 
;write character from a to console 
GeG2 mvil c,conout 
on a mov e,a scharacter to send 
cdg5@ call bdos ssend character 
c9 ret 
crlf: heat 
;send carriage return line feed 
3e0d mv a,cr sCcarriage return 
cdc8d call putchr 
3e8a mvi a,lf s;line feed 
cdc89 call putchr 
c9 ret 
prints 
;Drint the buffer addressed by de until $ 
dqd5 push d 
cdcfO call Crate 
dl pop d snew line 
0eB9 mvi c,pstring 
cdg5¢ call bdos sprint the string 
c9 ret 
readcom: 
;read the next command line to the conbuf 
116b@ lxi d,prompt 
cddag call print *command? 
eva mvi c,rstring 
117a@ 1lxi d,conbuf 
cdg50 call bdos eread command line 
; command line is present, scan it 
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91f3 219000 lxi h,@ ;Start with @dd0 
91f6 117co 1lxi d,conlin;command line 
G1f£9 la readc: ldax qd snext command character 
o™ Glfa 13 inx d -;to next command position 
Glfb b7 ora a scannot be end of command 
Qlfc c8 rz 
; not zero, numeric? 
$1fd d63¢ sui 6 
G1ff fea cpi 18 scarry if numeric 
@201 d213¢ jnc endrd 
: add-in next digit 
@204 29 dad h o%*2 
Q9205 4d Mov Cy 
9206 44 mov bn sbc = value * 2 
G@207 29 dad h 2 *4 
208 29 dad h tease 
9209 09 dad b °*2 + *8 = *19 
G@20a 85 add 1 s+digit 
G20b Of mov l,a 
G28c d2£9@ jnec readc >for another char 
O20f 24 inr h -overflow 
9218 c3£9@ jmp readc ;for another char 
endrd: 
: end of read, restore value ina 
9213 c63@ adi "“¢* *command 
9215 feé6él cpl ‘a’ translate case? 
G@217 d8 re 
; lower case, mask lower case bits 
@218 e65f ani 1@1S1111b 
lit @2la c9 ret 
RII IIIS OGIO OIG IOI IO III IOI tok 
«x * 
;* string data area for console messages 
« * * 
SOCIO IOI GIO IOI GIGI IGG III III IG k 
badver: 
@21lb 536£79 db ‘sorry, you need cp/m version 2S' 
nospace: 
O23a 4e6f29 db ‘no directory spaces' 
datmsg: 
@24d 5479790 db "type data: S$' 
errmsg: 
9259 457272 db ‘error, try again,S' 
prompt: 
G926b 4e6579 db "next command? $' 


ro) 
a 


4 


(All Information Contained Herein is Proprietary to Digital Research. ) 





eK KKKEKKKKEKK KEKE KKEKKKEKKKEKKKEKKEKEKREKEKKKKKKK KK ERKEEKE 


ox * 
;* fixed and variable data area ie 
ox * 
RGIS IIIS GIGI GIO III ICICI I 
@27a 21 conbuf: db conlen ;length of console buffer 
@27b consiz: ds 1 sresulting size after read 
Q27c conlin: ds 32 slength 32 buffer 
9821 = conlen equ $-consiz 
829¢ ds 32 :16 level stack 
stack: 
%2bec end 


Again, major improvements could be made to this particular 
program to enhance its operation, In fact, with some work, this 
program could evolve into a simple data base management system. One 
could, for example, assume a standard record size of 128 bytes, 
consisting of arbitrary fields within the record, A program, called 
GETKEY, could be developed which first reads a sequential file and 
extracts a specific field defined by the operator. For example, the 
command 


GETKEY NAMES.DAT LASTNAME 180 290 


would cause GETKEY to read the data base file NAMES.DAT and extract 
the "LASTNAME" field from each record, starting at position 18 and 
ending at character 20, GETKEY builds a table in memory consisting of 
each particular LASTNAME field, along witn its 16-bit record number 
location within the file. The GETKEY program then sorts this 1ist, 
and writes a new file, called LASTNAME. KEY, which is an alphabetical 


list of LASTNAME fields with their corresponding record numbers, 
(This list is called an "inverted index" in information retrieval 


parlance, ) 


Rename the program shown above as QUERY, and massage it a bit so 
that it reads a sorted key file into memory. The command line might 
appear as: 


QUERY NAMES.DAT LASTNAME, KEY 


Instead of reading a number, the QUERY program reads an alphanumeric 
string which is a particular key to find in the NAMES.DAT data base, 
Since the LASTNAME,KEY list is sorted, you can find a particular entry 
quite rapidly by performing a “binary search," similar to looking up a 
name in the telephone book. That is, starting at both ends of the 
list, you examine the entry halfway in between and, if not matched, 
split either the upper half or the lower half for the next’ search. 
you'll quickly reach the item you're looking for (in log2(n) steps) 
where you'll find the corresponding record number, Fetch and display 
this record at the console, just as we have done in the program shown 
above, 
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At this point you're just getting started. With a little more 
work, you can allow a fixed grouping size which differs from the 128 
byte record shown above. This is accomplished by keeping track of the 
record number as well as the byte offset within the record. Knowing 
the group size, you randomly access the record containing the proper 
group, offset to the beginning of the group within the record read 
sequentially until the group size has been exhausted, 


Finally, you can improve QUERY considerably by allowing boolean 
expressions which compute the set of records which satisfy several 
relationships, such as a LASTNAME between HARDY and LAUREL, and an AGE 
less than 45. Display all the records which fit this description. 
Finally, if your lists are getting too big to fit into memory, 
randomly access your key files from the disk as well. One note of 
consOlation after all this work: if you make it through the project, 
you'll have no more need for this manual! 
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6. 


FUNC FUNCTION NAME 


System Reset 
Console Input 
Console Output 
Reader Input 

Punch Output 

List Output 

Direct Console I/O 
Get I/O Byte 

Set I/O Byte 

Print String 

Read Console Buffer 
Get Console Status 


Return Version Number 


Reset Disk System 
Select Disk 

Open File 

Close File 

Search for First 
Search for Next 
Delete File 

Read Sequential 
Write Seguential 
Make File 

Rename File 

Return Login Vector 
Return Current Disk 
Set DMA Address 

Get Addr(Alloc) 
Write Protect Disk 
Get R/O Vector 

Set File Attributes 
Get Addr(disk parms) 
Set/Get User Code 
Read Random 

Write Random 
Compute File Size 
Set Random Record 


* Note that A = L, and B 
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INPUT PARAMETERS 


E = char 

see def 

none 

E = IOBYTE 
»Buffer 
DE = .Buffer 


O 
es) 
il 


none 

none 

E = Disk Number 
DE = .FCB 
DE = .FCB 
DE = .FCB 
none 

DE = .FCB 
DE = .FCB 
DE = .FCB 
DE = .FCB 
DE = .FCB 
none 

none 

DE = .DMA 
none 

none 

none 

DE = .FCB 
none 

see def 
DE = .FCB 
DE = .FCB 
DE = .FCB 
DE = .FCB 


H upon return 
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OUTPUT RESULTS 


see def 
A = IOBYTE 


see def 

A = @0/FF 

HL= Version* 
see def 

see def 

Dir Code 
Dir Code 
Dir Code 
Dir Code 
Dir Code 
Err Code 
Err Code 
Dir Code 
Dir Code 
Login Vect* 
Cur Disk# 


HL= .Alloc 
see def 

HL= R/O Vect* 
see def 

HL= .DPB 

see def 

A = Err Code 
A = Err Code 
94-815 FBZ 
es ia fe 
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ADDENDA TO: Utility Software Manual 
MACRO-80 Assembler Reference Manual 
XMACRO-86 Assembler Reference Manual 


The following features were added or modified in release 
Ste 


Add to Section 2.2.2 Switches 
Switch Action 


/M Initialize Block Data Areas. 

If the programmer wants the area that is defined 
by the DS (Define Space) pseudo-op initialized to 
zeros, then the programmer should use the /M 
Switch in the command line. Otherwise, the space 
is not guaranteed to contain zeros. That is, DS 
does not automatically initialize the space to 
zeros. 


/X% The presence or absence of /X in the command line 
sets the initial current mode and the initial 
value of the default for listing or suppressing 
lines in false conditional blocks. /X sets the 
current mode and initial value of default to 
not-to-list. No /X sets current mode and initial 
value of default to list. Current mode determines 
whether false conditionals will be listed or 
Suppressed. The initial value of the default is 
used with the .TFCOND pseudo-op so that .TFCOND is 
independent of .SFCOND and .LFCOND. it the 
program contains .SFCOND or .LFCOND, /X has no 
effect after .SFCOND or .LFCOND is’ encountered 
until a .TFCOND is encountered in the file. So /X 
has an effect only when used with a file that 
contains no conditional listing pseudo-ops or when 
used with .TFCOND. 
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The following chart illustrates the effects of the 
three pseudo-ops when encountered under /X and 
under no /X. See the addition to Section 2.6.27 
below ror a full description of the three 
conditional listing pseudo-ops. 


PSEUDO-OP NO /X [x 
(none) ON OFF 
_sréoxo oa mn 
pan Pe s 
prt fies em 55 
secon = i 
res on me 
. TFCOND ON OFF 
ion z ‘ 


Add to Section 2.6.26 Conditional Pseudo Overations 


IFIDN <argl>,<arg2> True if the string <argl> is 


IDeNtical to the string <arg2>. 
The angle brackets around <argl> 
and <arg2> are required. 


IFDIF <argl>,<arg2> True if the string <argl> is 


DIFferent from the string <arg2>. 
The angle brackets around <argl> 
and <arg2> are required. 
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Add to Section 2.6.27 Listing Control Pseudo Operations 


There are now five Listing control pseudo-ops. Output. t5 
the listing file- can Be <Gontrolled by the following 


pseudo-ops: 





*GiST, .ALIST, .~SEGUND,-.LFCOND, .TECOND 


The three new pseudo-ops control the listing of conditional 
pseudo-op blocks which evaluate as false. These pseudo-ops 
give the programmer control over four cases. 





1. Normally list false conditionals 
For this case, the programmer simply allows the 
default mode to control the listing. The default 
mode is list false conditionals. If the programmer 
decides to suppress false conditionals, the /X 
Switch can be issued in the command line instead of 
editing the source file. 





2. Normally suppress false conditionals 

For this case, the programmer issues the .TFCOND | 

Dpseudo-op in the program file. .TFCOND reverses | 

(toggles) the default, causing false conditionals | 

vo’ to be suppressed. If the programmer decides to | 
list false conditionals, the /X switch can be | 

issued in the command line instead of editing the | 

| 

| 


source file. 


3. Always suppress/list false conditionals | 
For these cases, the programmer issues either the 
-SFCOND pseudo-op to suppress false conditionals, 
Or the .LFCOND pseudo-op to list all false 
conditionals. 





For this case, the programmer has decided for most 

false conditionals whether to list or suporess, but 

for some false conditionals the programmer has not 

yet decided. For the false conditionals decided | 

about, use .SFCOND or .LFCOND. For those not yet | 

decided, use .TFCOND. .TFCOND sets the current and | 
| 
| 


| 
4. Suppress/list some false conditionals 
| 


default settings to the opposite of the default. 
Initially, the default is set by giving /X or no /X 
in the command line. Two subcases exist: 


1. The programmer wants some false conditionals | 
not to list unless /X is given. The programmer 
uses the .SFCOND and .LFCOND pseudo-ops to 
control which areas always suppress or list 

in’ false conditionals. To selectively suppress 
some false conditionals, the programmer issues 
-TFCOND at the beginning of the conditional 
block and again at the end of the conditional 
SLOCK. (NOTE: The second .TFCOND is should be 
so that the default setting will be the same as 
the initial setting. Leaving the default equal 


semechieeeninimeie iia) | 





MACRO-80, 


The three 
below. 
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PSEUDO-OP 


- SFCOND 


» LFCOND 


- TFCOND 


to the initial setting makes it easier to keep 
track of the default mode if there are many 
such areas.) If the conditional block evaluates 
as false, the lines will be suppressed. In 
this subcase, issuing the /X switch in the 
command line causes the conditional block 
affected by «TECOND: to*ilist even if it 
evaluates as false. 


The programmer wants some false conditionals to 
list unless /X is given. of the file. Two 
consecutive .TFCONDs places the conditional 
listing setting in initial state which is 
determined by the presence or absence of the /X 
Switch (the first .TFCOND sets the default to 
not initial; the second to initial). The 
selected conditional block then responds to the 
/X switch: if a /X switch is issued in the 
command line, the conditional block is 
suppressed if false; if no /X switch is issued 
in the command line, the conditional block is 
listed even if false. 


The programmer then must reissue the .SFCOND or 
- LFCOND conditional listing pseudo-op to 
restore the suppress or list mode. Simply 
issuing another .TFCOND will not restore the 
prior mode, but will toggle the default 
setting. Since in this subcase, the next area 
of code is supposed to list or suppress’ false 
conditionals always, the programmer must issue 
~SFCOND or .LFCOND. 


conditional listing pseudo-ops are summarized 


DEFINITION 


Suppresses the listing of conditional blocks 
that evaluate as false. 


Restores the listing of conditional blocks that 
evaluate as false. 


Toggles the current setting which controls’ the 
listing false conditionals. .TFCOND sets the 
current and default setting to not default. If 
a /X switch is given in the MACRO-80 run 
command line for a file which contains .TFCOND, 
/X reverses the effect of .TFCOND. 


> 
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Add to Section 2.7.9 Special Macro Operators and Forms 


% 


The percent sign is used only in a macro argument. 
%* converts the expression that follows it (usually a 


symbol) to a number in the current radix. During 
macro expansion, the number derived from converting 
the expression is substituted for the dummy. Using 


the % special operator allows a macro call by value. 
(Usually, a macro call is a call by reference with 
the text of the macro argument substituting exactly 
for the dummy.) 


The expression following the % must conform to the 
same rules as the DS (Define Space) pseudo-op. A 
valid expression returning a non-relocatable 
constant is required. 


EXAMPLE : 


Normally, LB, the argument to MAKLAB, would be 
Substituted for Y, the argument to MACRO, as a 
string. The % causes LB to be converted to a 
non-relocatable constant which is then substituted 
for Y. Without the % special operator, the result 
of assembly would be “Error LB” rather than “Error 
ca are 2 oe 


MAKLAB MACRO x 
ERR&Y: DB “Error &Y~,0 
ENDM 
MAKERR MACRO X 
LB SET 0 
REPT x 
LB SET LB+1L 
MAKLAB %LB 
ENDM 
ENDM 


When called by MAKERR 3, the assembler will 
generate: 


ERR1L: DB “Error 1°,0 
ERR2: DB “Error 2° ,0 
ERR3: DB ‘Srror. 3" ,0 


z 
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CHAPTER 1 


INTRODUCTION 


MACRO-80 is a relocatable macro assembler for 8080 and 2Z80 
microcomputer systems. It assembles 8080 or 280 code on any 
8080 or Z80 development system running the CP/M, ISIS-II, 
TRSDOS or TEKDOS operating system. The MACRO-80 package 
includes the MACRO-80 assembler, the LINK-80 linking loader, 
and the CREF-80 cross’ reference facility. CP/M versions 
also include the LIB-80 Library Manager. MACRO-80 resides 
in approximately 14K of memory and has an assembly rate of 
over 1000 lines per minute. 


MACRO-80 incorporates almost all "big computer" ‘assembler 
features without sacrificing speed or memory space. The 
assembler supports a complete, Intel standard macro 
facility, including IRP, IRPC, REPEAT, local variables and 
EXITM. Nesting of macros is limited only by memory. Code 
is assembled in relocatable modules that are manipulated 
with the flexible linking loader. Conditional assembly 
Capability is enhanced by an expanded set of conditional 
pseudo operations that include testing of assembly pass, 
symbol definition, and parameters to macros. Conditionals 
may be nested up to 255 levels. 


MACRO-80's linking loader provides a versatile array of 
loader capabilities, which are executed by means of easy 
command lines and switches. Any number of programs may be 
loaded with one command, relocatable modules may be loaded 
in user-specified locations, and external references between 
modules are resolved automatically by the loader. The 
loader also performs library searches for system subroutines 
and generates a load map of memory showing the locations of 
the main program and subroutines. The cross’ reference 
facility that is included in this package supplies a 
convenient alphabetic list of all program variable names, 
along with the line numbers where they are referenced and 
defined. 
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This manual is designed to serve as a reference guide to the 
MACRO-80 package. It defines, explains and gives examples 
Of all the features in MACRO-80 in terms that should be 
understandable to anyone familiar with assembly language 
programming. It is not intended, however, to serve as 
instructional material and presumes the user has substantial 
knowledge of assembly language programming. The user should 
refer to instructional material available from a variety of 
sources for additional tutorial information. 


CHAPTER 2 


MACRO-80 ASSEMBLER 


2.1 RUNNING MACRO-80 
The command to run MACRO-80 is 
M80 
MACRO-80 returns the prompt "*", indicating it is ready to 
accept commands. 
NOTE 
If you are uSing the TEKDOS 


operating system, see Appendix 
A for proper command formats. 


2.2 COMMAND FORMAT 


A command to MACRO-80 consists of a string of filenames with 
optional Switches. All filenames should follow the 
operating system's conventions for filenames and extensions. 
The default extensions supplied by Microsoft software are as 
follows: 


File CP/M ISIS-II1 
Relocatable object file REL REL 
Listing file PRN LST 
MACRO-80 source file MAC MAC 
FORTRAN source file FOR FOR 
COBOL source COB COB 


Absolute file COM 
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A command to MACRO-80 conveys the name of the source file to 
be assembled, the names of the file(s) to be created, and 
which assembly options are desired. The format of a 
MACRO-80 command is: 


objfile,lstfile=source file 


Only the equal sign and the source file field are required 
to create a relocatable object file with the default 
(source) filename and the default extension REL. 


Otherwise, an object file is created only if the objfile 
Field is filled, and a listing file is created only if the 
lstfile field is filled. 


To assemble the source file without producing an object file 
Or listing file, place only a comma to the left of the equal 
Sign. This is a handy procedure that lets you check for 
Syntax errors before assembling to an object file. 


Examples: 


*=TEST Assemble the source file TEST.MAC 
and place the object file in TEST.REL. 


*,=TEST Assemble the source file TEST.MAC 
without creating an object or listing 
file. Useful for error checking. 


TEST, TEST=TEST Assemble the source file TEST.MAC, 
placing the object file in TEST.REL 
and the listing file in TEST.PRN. 
(With ISIS-II, the listing file is 
TEST.LST. ) 


*OBJECT=TEST Assemble the source file TEST.MAC 
and place the object file in 
OBJECT. REL. 


OBJECT, LIST=TEST Assemble the source file TEST.MAC, 
placing the object file in OBJECT.REL 
and the listing file in LIST.PRN. 
(With ISIS-II, the listing file is 
LIST.LST. ) 


MACRO-80 also supports command lines; that is, the 
invocation and command may be typed on the same line. For 
example: 


M80 ,=TEST 
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2.2.1 Devices 


Any field in the MACRO-80 command string can also specify a 
device name. The default device name with the CP/M 
operating system is the currently logged disk. The default 
device name with the ISIS-II operating system is disk drive 
0. The command format is: 


dev:objfile,dev:lstfile=dev:source file 


The device names are as follows: 


Device CP/M ISIS-II 

Disk drives Ars (Bt, -Stsz585 sPO2, Fl ey. tF2t}) «2s 
Line printer LST: LST: 

Teletype or CRT Tiys TTY: 


High speed reader HSR 
Examples: 


*, TTY: =TEST Assemble the source file TEST.MAC 
and list the program on the 
console. No object code is 
generated. Useful for error check. 


*SMALL,TTY:=B:TEST Assemble TEST.MAC (found 
on disk drive B), place 
the object file in SMALL.REL, 
and list the program on the console. 


2.2.2 Switches 


A switch is a letter that is appended to the command string, 
preceded by a slash. It specifies an optional task to be 
performed during assembly. More than one switch can be 
used, but each must be preceded by a slash. (With the 
TEKDOS operating system, switches are preceded by commas. or 
spaces. See Appendix A.) All switches are optional. The 
available switches are: 


Switch Action 
0 Octal listing 
H Hexadecimal listing (default) 
R Force generation of an object file 
L Force generation of a listing file 
Cc Force generation of a cross reference file 











MACRO-80 ASSEMBLER PAGE 2-4 


Z Assemble Z80 opcodes (default for 280 operating 
systems) 

I Assemble 8080 opcodes (default for 8080 operating 
systems) 

P Each /P allocates an extra 256 bytes of stack 


Space for use during assembly. Use /P if stack 
overflow errors occur during assembly. Otherwise, 
not needed. 


M Initialize Block Data Areas. If the programmer 
wants the area that is defined by the DS (Define 
Space) speudo-op initialized to zeros, then the 
programmer should use the /M switch in the command 
line. Otherwise, the space is not guaranteed to 
contain zeros. That is, DS does not automatically 
initialize the space to zeros. 


X Usually used to suppress the listing of false 
conditionals. The following paragraph describes 
the /X switch more completely but in very 
technical terms. 


The presence or absence of /X in the command line 
sets the initial current mode and the initial 
value of the default for listing or suppressing 
lines in false conditional blocks. /X sets the 
current mode and initial value of default to 
not-to-list. No /X sets current mode and initial 
value of default to list. Current mode determines 
whether false conditionals will be listed or 
suppressed. The initial value of the default is 
used with the .TFCOND pseudo-op so that .TFCOND is 
independent of .SFCOND and_ .LFCOND. LE the 
program contains .SFCOND or .LFCOND, /X has no 
effect after .SFCOND or .LFCOND is’' encountered 
until a .TFCOND is encountered in the file. So /X 
has an effect only when used with a file that 
contains no conditional listing pseudo-ops or when 
used with .TFCOND. 
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Examples: 


*=TEST/L Assemble TEST.MAC, place the object file in 
TEST.REL and a listing file in TEST.PRN. 
(With ISIS-II, the listing file is 
TEST.LST. ) 


*=TEST/L/O Same as above, but listing file addresses 
will be in octal. 


*LAST=TEST/C Assemble TEST.MAC, place the object file in 
LAST. REL and cross reference file in 
TEST.CRF. (See Chapter 3.) 


2.3 FORMAT OF MACRO-80 SOURCE FILES 
Input source lines of up to 132 characters in length are 
acceptable. 


MACRO-80 preserves lower case letters in quoted strings’ and 
comments. All symbols, opcodes and pseudo-opcodes typed in 
lower case will be converted to upper case. 


If the source file includes line numbers from an editor, 
each byte of the line number must have the high bit on. 
Line numbers from Microsoft's EDIT-80 Editor are acceptable. 


2.3.1 Statements 


Source files input to MACRO-80 consist of statements of the 
form: 


[label:[{:]] [operator] [arguments] [;comment] 


With the exception of the ISIS assembler $ controls (see 
Section 2.11), it is not necessary that statements begin in 
column 1. Multiple blanks or tabs may be used to improve 
readability. 


If a label is present, it is the first item in the statement 
and is immediately followed by a colon. If it is followed 
by two colons, it is declared as PUBLIC (see ENTRY/PUBLIC, 
Section 2.6.10). For exmple: 

FOO: : RET 
is equivalent to 


PUBLIC FOO 
FOO: RET 
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The next item after the label, or the first item on the line 
if no label is present, is an operator. An operator may be 
an 8086 mnemonic, pseudo-op, macro call or expression. The 
evaluation order is as follows: 


1. Macro call 
2. Mnemonic/Pseudo operation 
3. Expression 


Instead of flagging an expression as an error, the assembler 
treats it as if it were a DB statement (see Section 2.6.4). 


The arguments following the operator will, of course, vary 
in form according to the operator. 


A comment always begins with a semicolon and ends with a 
Carriage return. A comment may be a line by itself or it 
may be appended to a line that contains a statement. 
Extended comments can be entered uSing the .COMMENT pseudo 
operation (see Section 2.6.20). 


2.3.2 Symbols 


MACRO-80 symbols may be of any length, however, only the 
first six characters are significant. The following 
characters are legal in a symbol: 


A-Z 0-9 $ ‘ ? @ 


With Microsoft's 8080/2Z80/8086 assemblers, the underline 
character is also legal in a symbol. A symbol may not start 
with a digit. When a symbol is read, lower case is 
translated into upper case. If a symbol reference is 
followed by ## it is declared external (see also the 
EXT/EXTRN pseudo-op, Section 2.6.12). 


2.3.3 Numeric Constants 


The default base for numeric constants is decimal. This may 
be changed by the .RADIX pseudo-op (see Section 2.6.22). 
Any base from 2 (binary) to 16 (hexadecimal) may be 
selected. When the base is greater than 10, A-F are the 
digits following 9. If the first digit of the number is not 
numeric the number must be preceded by a zero. 
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Numbers are 16-bit unsigned quantities. A number is’ always 
evaluated in the current radix unless one of the following 
special notations is used: 


nnnnB Binary 

nnnnD Decimal 

nnnno Octal 

nnnnQ Octal 

nnnnH Hexadecimal 
X'nnnn! Hexadecimal 


Overflow of a number beyond two bytes is ignored and_ the 
result is the low order 16-bits. 


A character constant is a string comprised of zero, one or 
two ASCII characters, delimited by quotation marks, and used 
in a non-simple expression. For example, in the statement 


DB 'A' + 1 
'A' is a character constant. But the statement 
DB ‘A: 


> uses 'A' as a string because it is in a simple expression. 
The rules for character constant delimiters are the same as 
for strings. 


A character constant comprised of one character has as its 
value the ASCII value of that character. That is, the high 
Order byte of the value is zero, and the low order byte is 
the ASCII value of the character. For example, the value of 
the constant ‘'A' is 41H. 


A character constant comprised of two characters has as its 
value the ASCII value of the first character in the high 
Order byte and the ASCII value of the second character in 
the low order byte. For example, the value of the character 
constant "AB" is 41H*256+42H. 


2.3.4 Strings 


A string is comprised of zero or more characters delimited 
by quotation marks. Either single or double quotes may be 
used as string delimiters. The delimiter quotes may be used 
as characters if they appear twice for every character 
occurrence desired. For example, the statement 

f’ DB "I am ""great"" today" 
Stores the string 


I am "great" today 


TCT ne 
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If there are zero characters between the delimiters, the 
string is a null string. wo 


2.4 EXPRESSION EVALUATION 


2.4.1 Arithmetic And Logical Operators 


The following operators are allowed in expressions. The 
Operators are listed in order of precedence. 


NUL 
LOW, HIGH 

*, /, MOD, SHR, SHL 

Unary Minus 

oe 

EQ, NE, LT, LE, GT, ‘GE 

NOT 

AND Ww 
OR, XOR 


Parentheses are used to change the order of precedence. 
During evaluation of an expression, aS soon as a new 
Operator is encountered that has precedence less than or 
equal to the last operator encountered, all operations up to 
the new operator are performed. That is, subexpressions 
involving operators of higher precedence are computed first. 


All operators except +, -, *, / must be separated from their 
operands by at least one space. 


The byte isolation operators (HIGH, LOW) isolate the high or 
low order 8 bits of an Absolute 16-bit value. If a 
relocatable value is supplied as an operand, HIGH and LOW 
will treat it as if it were relative to location zero. 


2.4.2 Modes 


All symbols used as operands in expressions are in one of 
the following modes: Absolute, Data Relative, Program 
(Code) Relative or COMMON. (See Section 2.6 for the ASEG, 
CSEG, DSEG and COMMON pseudo-ops.) Symbols assembled under 
the ASEG, CSEG (default), or DSEG pseudo-ops are in 
Absolute, Code Relative or Data Relative mode respectively. 
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The number of COMMON modes in a program is determined by the 
number of COMMON blocks that have been named with the COMMON 
pseudo-op. Two COMMON symbols are not in the same mode 
unless they are in the same COMMON block. [In any operation 
Other than addition oor subtraction, the mode of both 
operands must be Absolute. 


If the operation is addition, the following rules apply: 
1. At least one of the operands must be Absolute. 
2. Absolute + <mode> = <mode> 

If the operation is subtraction, the following rules apply: 
1. <mode> - Absolute = <mode> 


2. <mode> — <mode> = Absolute 
where the two <mode>s are the same. 


Each intermediate step in the evaluation of an expression 
must conform to the above rules for modes, or an error will 
be generated. For example, if FOO, BAZ and ZAZ are _ three 
Program Relative symbols, the expression 


FOO + BAZ - ZAZ 


will generate an R error because the first step (FOO + BAZ) 
adds two relocatable values. (One of the values must be 
Absolute.) This problem can always be fixed by inserting 
parentheses. So that 


FOO + (BAZ - ZAZ) 


is legal because the first step (BAZ - ZAZ) generates. an 
Absolute value that is then added to the Program Relative 
value, FOO. 


2.4.3 Externals 


Aside from its classification by mode, a symbol is either 
External or not External. (See EXT/EXTRN, Section 2.6.12.) 
An External value must be assembled into a two-byte field. 
(Single-byte Externals are not supported.) The following 
rules apply to the use of Externals in expressions: 


1. Externals are legal only in addition and 
subtraction. 


2. If an External symbol is used in an expression, the 
result of the expression is always External. 


3. When the operation is addition, either operand (but 
not both) may be External. 





——— an a 
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4. When the operation is subtraction, only the first 
operand may be External. Ww 


2.5 OPCODES AS OPERANDS 


8080 opcodes are valid one-byte operands. Note that only 
the first byte is a valid operand. For example: 


MVI A, (JMP) 
ADI (CPT) 

MVI B, (RNZ) 
CPI (INX H) 
ACI (LXI B) 


MVI C,MOV A,B 
Errors will be generated if more than one byte is’ included 
in the operand -- such as (CPI 5), LXI B,LABEL1) or (JMP 
LABEL2) . 


Opcodes used as one-byte operands need not be enclosed in 
parentheses. 


NOTE W 


Opcodes are not valid operands 
in Z80 mode. 
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2.6 PSEUDO OPERATIONS 
Zs 6. 1 ASEG 
ASEG 


ASEG sets the location counter to an absolute segment of 
memory. The location of the absolute counter will be that 
of the last ASEG (default is 0), unless an ORG is done after 
the ASEG to change the location. The effect of ASEG is also 
achieved by using the code segment (CSEG) pseudo operation 
and the /P switch in LINK-80. See also Section 2.6.28 


2.6.2 COMMON 
COMMON /<block name>/ 


COMMON sets the location counter to the selected common 
block in memory. The location is always the beginning of 
the area so that compatibility with the FORTRAN COMMON 
Statement is maintained. If <block name> is omitted or 
consists of spaces, it is considered to be blank common. 
See also Section 2.6.28. 


2.6.3 CSEG 
CSEG 


CSEG sets the location counter to the code relative segment 
of memory. The location will be that of the last CSEG 
(default is 0), unless an ORG is done after the CSEG to 
change the location. CSEG is the default condition of the 
assembler (the INTEL assembler defaults to ASEG). See also 
Section 2.6.28. 


2.6.4 DB - Define Byte 

DB <exp>[,<exp>...] 

DB <string>[<string>...] 
The arguments to DB are either expressions or strings. DB 
Stores the values of the expressions or the characters of 


the strings in successive memory locations beginning with 
the current location counter. 
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Expressions must evaluate to one byte. (If the high byte of 
the result is 0 or 255, no error is given; otherwise, an A 
error results.) 


Strings of three or more characters may not be used in 
expressions (i.e., they must be immediately followed by a 
comma or the end of the line). The characters in a string 
are stored in the order of appearance, each as a one-byte 
value with the high order bit set to zero. 


Example: 
0000' 41 42 DB "AB! 
0002' 42 DB 'AB' AND OFFH 
0003' 41 42 43 DB "ABC! 


2.6.5 DC - Define Character 
DC <string> 


DC stores the characters in <string> in successive memory 
locations beginning with the current location counter. As 
with DB, characters are stored in order of appearance, each 
as a one-byte value with the high order bit set to zero. 
However, DC stores the last character of the string with the 
high order bit set to one. An error will result if the 
argument to DC is a null string. 


2.6.6 DS - Define Space 
DS <exp> 


DS reserves an area of memory. The value of <exp> gives the 
number of bytes to be allocated. All names used in <exp> 
must be previously defined (i.e., all names known at that 
point on pass 1). Otherwise, a V error is generated during 
pass l1 and a U error may be generated during pass 2. If aU 
error is not generated during pass 2, a phase error will 
probably be generated because the DS generated no code on 
pass l. 


ie es DSEG 
DSEG 
DSEG sets the location counter to the Data Relative segment 


of memory. The location of the data relative counter will 
be that of the last DSEG (default is 0), unless an ORG is 
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done after the DSEG to change the location. See also 
Section 2.6.28. 


2.6.8 DW - Define Word 
DW <exp>[,<exp>...] 


DW stores the values of the expressions in successive memory 
locations beginning with the current location counter. 
Expressions are evaluated as 2-byte (word) values. 


2.6.9 END 
END [<exp>] 


The END statement specifies the end of the program. If 
<exp> 1S present, it is the start address of the program. 
If <exp> is not present, then no start address is passed to 
LINK-80 for that program. 


NOTE 


bi an assembly language 
program is the main program, a 
start address (label) must be 
specified. If not, LINK-80 
will issue a "no start 
address" error. Lt the 
program is a subroutine to a 
FORTRAN program (for example), 
the start address is not 
required because FORTRAN has 
supplied one. 


2.6.10 ENTRY/PUBLIC 


ENTRY <name>[,<name>...] 
or 
PUBLIC <name>[,<name>...|] 


ENTRY or PUBLIC declares each name in the list as_ internal 
and therefore available for use by this program and other 
programs to be loaded concurrently. All of the names in the 
list must be defined in the current program or a U error 
results. An M error is generated if the name is an external 
name or common-blockname. 




















( 





| 
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2.6.11 EQU 
<name> EQU <exp> 


EQU asSigns the value of <exp> to <name>. If <exp> is 
external, an error is generated. If <name> already has a 
value other than <exp>, an M error is generated. 


2.6.12 EXT/EXTRN 


EXT <name>[,<name>... ] 
Or 
EXTRN <name>[,<name>...|] 


EXT or EXTRN declares that the name(s) in the list are 
external (i.e., defined in a different program). If any 
item in the list references a name that is defined in the 
Current program, an M error results. A reference to a name 
where the name is followed immediately by two pound. signs 
(e.g., NAME##) also declares the name as external. 


2.6.13 INCLUDE 
INCLUDE <filename> 


The INCLUDE pseudo-op applies only to CP/M versions of 
MACRO-80. The pseudo-ops INCLUDE, SINCLUDE and MACLIB are 
synonymous. 


The INCLUDE pseudo-op assembles source statements from an 
alternate source file into the current source file. Use of 
INCLUDE eliminates the need to repeat an often-used sequence 
of statements in the current source file. 


<filename> is any valid specification, as determined by the 
operating system. Defaults for filename extensions and 
device names are the same as those in a MACRO-80 command 
line. 


The INCLUDE file is opened and assembled into the current 
source file immediately following the INCLUDE statement. 
When end-of-file is reached, assembly resumes with the 
Statement following INCLUDE. 


On a MACRO-80 listing, a plus sign is printed between the 
assembled code and the source line on each line assembled 
from an INCLUDE file. (See Section 2.12.) 


Nested INCLUDES are not allowed. If encountered, they will 
result in an objectionable syntax error 'O'. 
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The file specified in the operand field must exist. If the 
file is not found, the error 'V' (value error) is given, and 
the INCLUDE is ignored. 


2.6.14 NAME 
NAME ('modname ' ) 


NAME defines a name for the module. Only the first six 
characters are significant in a module name. A module name 
may also be defined with the TITLE pseudo-op. In the 
absence of both the NAME and TITLE pseudo-ops, the module 
name is created from the source file name. 


2.6.15 ORG - Define Origin 
ORG <exp> 


The location counter is set to the value of <exp> and _ the 
assembler assigns generated code starting with that value. 
All names used in <exp> must be Known on pass 1, and _ the 
value must either be absolute or in the same area as the 
location counter. 


2.6.16 PAGE 
PAGE [<exp>] 


PAGE causes the assembler to start a new output page. The 
value of <exp>, if included, becomes the new page size 
(measured in lines per page) and must be in the range 10 to 
255% The default page size is 50 lines per page. The 
assembler puts a form feed character in the listing file at 
the end of a page. 


2.6.17 SET 
<name> SET <exp> 


SET is the same as EQU, except no error is generated if 
<name> is already defined. 
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2e0¢L5 -SUBTTL 
SUBTTL <text> 


SUBTTL specifies a subtitle to be listed on the line after 
the title (see TITLE, Section 2.6.19) on each page heading. 
<text> is truncated after 60 characters. Any number of 
SUBTTLS may be given in a program. 


2.6.19 TITLE 
TITLE <text> 


TITLE specifies a title to be listed on the first line of 
each page. If more than one TITLE is given, a Q error 
results. The first six characters of the title are used as 
the module name unless a NAME pseudo operation is used. If 
neither a NAME or TITLE pseudo-op is used, the module name 
1s created from the source filename. 


2.6.20 .COMMENT 
~COMMENT <delim><text><delim> 


The first non-blank character encountered after .COMMENT is 
the delimiter. The following <text> comprises a comment 
block which continues until the next occurrence of 
<delimiter> is encountered. For example, using an asterisk 
as the delimiter, the format of the comment block would be: 


«COMMENT * 
any amount of text entered 
here as the comment block 


* 
ereturn to normal mode 
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2484.24 - PRINTX 
»~PRINTX <delim><text><delim> 


The first non-blank character encountered after .PRINTX is 
the delimiter. The following text is listed on the terminal 
during assembly until another occurrence of the delimiter is 
encountered. -PRINTX is useful for displaying progress 
through a long assembly or for displaying the value of 
conditional assembly switches. For example: 


LE CPM 
»PRINTX /CPM version/ 
ENDIF 


NOTE 


~-PRINTX will output on both 
passes. If only one printout 
is desired, use the IFl or IF2 
pseudo-op. For example: 


IF2 

IF CPM 

»PRINTX /CPM version/ 
ENDIF 

ENDIF 


will only print if CPM is true 
and M80 is in pass 2. 


2.6.22 .RADIX 
RADIX <exp> 


The default base (or radix) for all constants is decimal. 
The .RADIX statement allows the default radix to be changed 
to any base in the range 2 to 16. For example: 


MOVI BX, OF FH 
-RADIX 16 
MOVI BX, OFF 


The two MOVIs in the example are identical. The <exp> in a 
»~RADIX statement is always in decimal radix, regardless of 


the current radix. 


a 





a 
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260.23 «280 


.Z80 enables the assembler to accept 280 opcodes. This is 
the default condition when the assembler is running on a Z80 
Operating system. 280 mode may also be set by appending the 
Z Switch to the MACRO-80 command string -- see Section 
2ecees 


2.6.24 .8080 


-8080 enables the assembler to accept 8080 opcodes. This is 
the default condition when the assembler is running on an 
8080 operating system. 8080 mode may also be set by 
appending the I switch to the MACRO-80 command string -- see 
Section 2.2.2. 


2.6.25 - REQUEST 
REQUEST <filename>[,<filename>...|] 


-REQUEST sends a request to the LINK-80 loader to search the a, 
filenames in the list for undefined globals. The filenames 

in the list should be in the form of legal symbols. They 

should not include filename extensions Or disk 
specifications. LINK-80 supplies a default extension and 

assumes the default disk drive. 
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2.6.26 Conditional Pseudo Operations 


The conditional pseudo operations are: 


IF/IFT <exp> True if <exp> is not 0. 
IFE/IFF <exp> True if <exp> is 0. 

IF1l True if pass l. 

IF2 True if pass 2. 

IFDEF <symbol> True if <symbol> is defined or 


has been declared External. 


IFNDEF <symbol> True if <symbol> is undefined 
Or not declared External. 


IFB <arg> True if <arg> is blank. The 
angle brackets around <arg> 
are required. 


IFNB <arg> True if <arg> is not blank. 
Used for testing when dummy 
parameters are supplied. The 
angle brackets around <arg> 
are required. 


IFIDN <argl>,<arg2> True if the string <argl> is 
IDeNtical to the string 
<arg2>. 


The angle brackets around 
<argl> and <arg2> are 
required. 


IFDIF <argl>,<arg2> True if the string <argl> is 
DIFferent from the string 
<arg2>. 

The angle brackets around 
<argl> and <arg2> are 
required. 


All conditionals use the following format: 


IFxx [argument] 


[ELSE 
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Conditionals may be nested to any level. Any argument to a 
conditional must be known on pass 1 to avoid V errors and 
incorrect evaluation. For IF,., IFT, IFF,.. and IFE the 
expression must involve values which were previously defined 
and the expression must be absolute. If the name is defined 
after an IFDEF or IFNDEF, pass 1 considers the name to be 
undefined, but it will be defined on pass 2. 


2.6.26.1 ELSE - Each conditional pseudo operation may 
optionally be used with the ELSE pseudo operation which 
allows alternate code to be generated when the opposite 
condition exists. Only one ELSE is permitted for a given 
IF, and an ELSE is always bound to the most recent, open IF. 
A conditional with more than one ELSE or an ELSE without a 
conditional will cause aC error. 


2.6.26.2 ENDIF - Each IF must have a matching ENDIF to 
terminate the conditional. Otherwise, an ‘Unterminated 
conditional’ message is generated at the end of each pass. 
An ENDIF without a matching IF causes aC error. 


2.6.27 Listing Control Pseudo Operations 


Output to the listing file can be controlled by two 
pseudo-ops: 


pilot and ~XLIST 


If a listing is not being made, these pseudo-ops have no 
effect. -LIST is the default condition. When a .XLIST is 
encountered, source and object code will not be listed until 
a .LIST is encountered. 


The output of false conditional blocks is controlled by 
three pseudo-ops: .SFCOND, .LFCOND, and .TFCOND. 


These pseudo-ops give the programmer control over four 
cases. 


1. Normally list false conditionals 
For this case, the programmer simply allows’ the 
default mode to control the listing. The default 
mode is list false conditionals. If the programmer 
decides to suppress false conditionals, the /X 
switch can be issued in the command line instead of 
editing the source file. 
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Ze 


Normally suppress false conditionals 

For this case, the programmer issues the .TFCOND 
pseudo-op in the program file. .TFCOND reverses 
(toggles) the default, causing false conditionals 
to be suppressed. If the programmer decides to 
list false conditionals, the /X switch can be 
issued in the command line instead of editing the 
source file. 


Always suppress/list false conditionals 

For these cases, the programmer issues either the 
» SFCOND pseudo-op to always suppress false 
conditionals, or the .LFCOND pseudo-op to always 
list all false conditionals. 


Suppress/list some false conditionals 

For this case, the programmer has decided for most 
false conditionals whether to list or suppress, but 
for some false conditionals the programmer has not 
yet decided. For the false conditionals decided 
about, use .SFCOND or .LFCOND. For those not yet 
decided, use .TFCOND. .TFCOND sets the current and 
default settings to the opposite of the default. 
Initially, the default is set by giving /X or no /X 
in the command line. Two subcases exist: 


1. The programmer wants some false conditionals 
not to list unless /X is given. The programmer 
uses the .SFCOND and .LFCOND pseudo-ops’ to 
control which areas always suppress or list 
false conditionals. To selectively suppress 
some false conditionals, the programmer issues 
~TFCOND at the beginning of the conditional 
block and again at the end of the conditional 
block. (NOTE: The second .TFCOND should be 
issued so that the default setting will be the 
same as the initial setting. Leaving the 
default equal to the initial setting makes it 
easier to keep track of the default mode if 
there are many such areas.) If the conditional 
block evaluates as false, the lines will be 
suppressed. In this subcase, issuing the /X 
Switch in the command line causes the 
conditional block affected by .TFCOND to list 
even if it evaluates as false. 
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The three 
below. 


PSEUDO-OP 


- SFCOND 


- LFCOND 


- TFCOND 


Ls 


The programmer wants some false conditionals to 
list unless /X is’ given. Two consecutive 
-TFCONDs places the conditional listing setting 
in initial state which is determined by the 
presence or absence of the /X switch in the 
command line (the first .TFCOND sets’ the 
default to not initial; the second to 
initial). The selected conditional block then 
responds to the /X switch: if a /X switch is 
issued in the command line, the conditional 
block is suppressed if false; if no /X switch 
is issued in the command line, the conditional 
block is listed even if false. 


The programmer then must reissue the .SFCOND or 
» LFCOND conditional listing pseudo-op to 
restore the suppress or list mode. Simply 
issuing another .TFCOND will not restore the 
prior mode, but will toggle the default 
setting. Since in this subcase, the next area 
of code is supposed to list or suppress’ false 
conditionals always, the programmer must issue 
~SFCOND or .LFCOND. 


conditional listing pseudo-ops are summarized 


DEFINITION 


Suppresses the listing of conditional blocks 
that evaluate as false. 


Restores the listing of conditional blocks that 
evaluate as false. 


Toggles the current setting which controls’ the 
listing false conditionals. .TFCOND sets the 
current and default setting to not default. If 
a /X switch is given in the MACRO-80 run 
command line for a file which contains .TFCOND, 
/X reverses the effect of .TFCOND. 
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The following chart illustrates the effects of the three 
pseudo-ops when encountered under /X and under no /X. 


PSEUDO-OP NO /X /X 
(none) ON OFF 
_sréono oi oi 
iti és of 
oe a a 
wast 2 e 
_sréowo oi oi 
men ae s 
. TFCOND ON OFF 
parr ca 2 


The output of cross reference information is controlled by 
~CREF and .XCREF. If the cross reference facility (see 
Chapter 3) has not been invoked, .CREF and .XCREF have no 
effect. The default condition is .CREF. When a .XCREF is 
encountered, no cross reference information is output until 
»~CREF is encountered. 


The output of MACRO/REPT/IRP/IRPC expansions is controlled 
by three pseudo-ops: .LALL, .SALL, and .XALL. .LALLlists 
the complete macro text for all expansions. » SALL 
suppresses lsiting of all text and object code produced by 
macros. .XALL is the default condition; a source line is 


listed only if it generates object code. 
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2.6.28 Relocation Pseudo Operations 


The ability to create relocatable modules is one of the 
major features of Microsoft assemblers. Relocatable modules 
offer the advantages of easier coding and faster testing, 
debugging and modifying. In addition, it is possible to 
specify segments of assembled code that will later be loaded 
into RAM (the Data Relative segment) and ROM/PROM (the Code 
Relative segment). The pseudo operations’ that select 
relocatable areas are CSEG and DSEG. The ASEG pseudo-op is 
used to generate non-relocatable (absolute) code. The 
COMMON pseudo-op creates a common data area for every COMMON 
block that is named in the program. 


The default mode for the assembler is Code Relative. That 
is, assembly begins with a CSEG automatically executed and 
the location counter in the Code Relative mode, pointing to 
location 0 in the Code Relative segment of memory. All 
subsequent instructions will be assembled into the Code 
Relative segment of memory until an ASEG or DSEG or COMMON 
pseudo-op is executed. For example, the first DSEG 
encountered sets the location counter to location zero in 
the Data Relative segment of memory. The following code is 
assembled in the Data Relative mode, that is, it is assigned 
to the Data Relative segment of memory. If a subsequent 
CSEG is encountered, the location counter will return to the 
next free location in the Code Relative segment and so on. 


The ASEG, DSEG, CSEG pseudo-ops never have operands. If you 
wish to alter the current value of the location counter, use 
the ORG pseudo-op. 


2.6.28.1 ORG Pseudo-op - At any time, the value 
of the location counter may be changed by use of the the ORG 
pseudo-op. The form of the ORG statement is: 


ORG <exp> 


where the value of <exp> will be the new value of the 
location counter in the current mode. All names used in 
<exp> must be known on pass 1 and the value of <exp> must be 
either Absolute or in the current mode of the location 
counter. For example, the statements 


DSEG 
ORG 50 


set the Data Relative location counter to 50, relative to 
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2.6.28.2 LINK-80 - The LINK-80 linking loader (see 
Chapter 4 of this manual) combines the segments and creates 
each relocatable module in memory when the program is 
loaded. The origins of the relocatable segments are not 
fixed until the program is loaded and the origins are 
assigned by LINK-80. The command to LINK-80 may contain 
user-specified origins through the use of the /P (for Code 
Relative) and /D (for Data and COMMON segments) switches. 





For example, a program that begins with the statements 


ASEG 
ORG 800H 


and is assembled entirely in Absolute mode will always load 
beginning at 800 unless the ORG statement is changed in the 
source file. However, the same program, assembled in Code 
Relative mode with no ORG statement, may be loaded at any 
specified address by appending the /P:<address> switch to 
the LINK-80 command string. 


2.6.29 Relocation Before Loading 


Two pseudo-ops, .PHASE and .DEPHASE, allow code to be 
located in one area, but executed only at a different, 


specified area. 


For example: 


0000° -PHASE 100H 
0100 E8 0003 FOO : CALL BAZ 
0103 ES FFOL JMP ZOO 
0106 G3 BAZ: RET 

. DEPHASE 
0007' E9 FFFB ZOO: JMP 5 


All labels within a .PHASE block are defined as the absolute 
value from the origin of the phase area. The code, however, 
is loaded in the current area (i.e., from 0' in this 
example). The code within the block can later be moved to 
LOOH and executed. 


2.7 MACROS AND BLOCK PSEUDO OPERATIONS 

The macro facilities provided by MACRO-80 include three 
repeat pseudo operations: repeat (REPT), indefinite repeat 
(IRP), and indefinite repeat character (IRPC). A macro 
Gefinition operation (MACRO) is also provided. Each of 
these four macro operations is terminated by the ENDM pseudo 


operation. 
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2./.1 Terms 


For the purposes of discussion of macros and block 
Operations, the following terms will be used: 


1. <dummy> 1S used to represent a dummy parameter. 
All dummy parameters are legal symbols that appear 
in the body of a macro expansion. 


2. <dummylist> is a list of <dummy>s' separated by 
commas. 


3. <arglist> is a list of arguments separated by 
commas. <arglist> must be delimited by angle 
brackets. Two angle brackets with no intervening 
characters (<>) or two commas with no intervening 
Characters enter a null argument in the list. 
Otherwise an argument is a character or series of 
characters terminated by a comma or >. With angle 
brackets that are nested inside an <arglist>, one 
level of brackets is removed each time the 
bracketed argument is used in an <arglist>. See 
example, Section 2.7.5.) A quoted string is an 
acceptable argument and is passed as such. Unless 
enclosed in brackets or a quoted string, leading 
and trailing spaces are deleted from arguments. 


4, <paramlist> is used to represent a list of actual 
Parameters separated by commas. No delimiters are 
required (the list is terminated by the end of line 
Or a comment), but the rules for entering null 
parameters and nesting brackets are the same _ as 
described for <arglist>. (See example, Section 
25142) 


2./.2 REPT-ENDM 


REPT <exp> 


ENDM 


The block of statements between REPT and ENDM is’ repeated 
<exp> times. <exp> is evaluated as a 16-bit unsigned 
number. If <exp> contains any external or undefined terms, 
an error is generated. Example: 


SET 0Q we 


REPT 10 sgenerates DB 1 —- DB 10 
SET X+l 

DB X 

ENDM 
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2.7.3 IRP-ENDM 


IRP <dummy>,<arglist> 


ENDM 


The <arglist> must be enclosed in angle brackets. The 
number of arguments in the <arglist> determines the number 
of times the block of statements is repeated. Each 
repetition substitutes the next item in the <arglist> for 
every occurrence of <dummy> in the block. If the <arglist> 
is null (i.e., <>), the block is processed once with each 
occurrence of <dummy> removed. For example: 


IRP X,<1,2,3,4,5,6,7,8,9,10> 
DB X 
ENDM 


generates the same bytes as the REPT example. 


2.7.4 IRPC-ENDM 


IRPC <dummy>,string (or <string>) 


ENDM 
IRPC is similar to IRP but the arglist is replaced by a 
String of text and the angle brackets around the string are 
optional. The statements in the block are repeated once for 
each character in the string. Each repetition substitutes 


the next character in the string for every occurrence of 
<dummy> in the block. For example: 


IRPC X,0123456789 
DB X+l1 
ENDM 


generates the same code as the two previous examples. 


rr = 
re 
cai 
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2.7.5 MACRO 


Often it is convenient to be able to generate a given 
sequence of statements from various places in a program, 
even though different parameters may be required each time 
the sequence is used. This capability is provided by the 
MACRO statement. 

The form is 


<name> MACRO <dummylist> 


ENDM 


where <name> conforms to the rules for forming symbols. 
<name> is the name that will be used to invoke the macro. 
The <dummy>s in <dummylist> are the parameters that will be 
Changed (replaced) each time the MACRO is invoked. The 
Statements before the ENDM comprise the body of the macro. 
During assembly, the macro is expanded every time it is 
invoked but, unlike REPT/IRP/IRPC, the macro is not expanded 
when it is encountered. 


The form of a macro call is 
<name> <paramlist> 


where <name> is the name supplied in the MACRO definition, 
and the parameters in <paramlist> will replace the <dummy>s 
in the MACRO <dummylist> on a one-to-one basis. The number 
of items in <dummylist> and <paramlist> is limited only by 
the length of a line. The number of parameters used when 
the macro is called need not be the same as the number of 
<dummy>s in <dummylist>. If there are more parameters’ than 
<dummmy>s, the extras are ignored. If there are fewer, the 
extra <dummy>s will be made null. The assembled code will 
contain the macro expansion code after each macro call. 


NOTE 


A dummy parameter in a 
MACRO/REPT/IRP/IRPC is always 
recognized exclusively as a 
dummmy parameter. Register 
names such as A and B will be 
changed in the expansion if 
they were used as dummy 
parameters. 
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Here is an example of a MACRO definition that defines a 
macro called FOO: 
FOO MACRO X 
R 4 SET 0 
REPT x 
ad SET Y+1 
DB b 
ENDM 
ENDM 
This macro generates the same code as the previous’ three 
examples when the call 
FOO 10 
is executed. 
Another example, which generates the same code, illustrates 
the removal of one level of brackets when an argument is 
used as an arglist: 
FOO MACRO Xx 
IRP Y,<X> 
_ DB b 
ENDM 
ENDM 
When the call 
FOO <1,2,3,4,5,6,7,8,9,10> 
is made, the macro expansion looks like this: 
IRP Y¥,<1427374,5,6,7,8,9,10> 
DB Y | 
ENDM | 
2.7.6 ENDM 
Every REPT, IRP, IRPC and MACRO pseudo-op must be terminated 
with the ENDM pseudo-op. Otherwise, the ‘'Unterminated 
REPT/IRP/IRPC/MACRO' message is generated at the end of each 
pass. An unmatched ENDM causes an O error. 
2.7.7 EXITM 
o ae 


The EXITM pseudo-op is used to terminate a REPT/IRP/IRPC or 
MACRO call. When an EXITM is executed, the expansion is 
exited immediately and any remaining expansion or repetition 
is not generated. If the block containing the EXIT is 
nested within another block, the outer level continues to be 
expanded. 


qr 
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25-448  . LOCAL 
LOCAL <dummylist> 


The LOCAL pseudo-op is allowed only inside a MACRO 
definition. When LOCAL is executed, the assembler creates a 
unique symbol for each <dummy > in <dummylist> and 
Substitutes that symbol for each occurrence of the <dummy> 
in the expansion. These unique symbols are usually used to 


define a label within a macro, thus eliminating 
multiply-defined labels on successive expansions of the 
macro. The symbols created by the assembler range from 


--Q0001 to ..FFFF. Users will therefore want to avoid the 
form ..nnnn for their own symbols. If LOCAL statements are 
used, they must be the first statements in the macro 
definition. 


2.7.9 Special Macro Operators And Forms 


& The ampersand is used in a macro expansion to 
concatenate text or symbols. A dummy parameter that 
is in a quoted string will not be substituted in the 
expansion unless it is immediately preceded by &. 
To form a symbol from text and a dummy, put & 
between them. For example: 


ERRGEN MACRO X 


ERROR&X : PUSH BX 
MOVI BX, '&X' 
JMP ERROR 
ENDM 


In this example, the call ERRGEN A will generate: 


ERRORA: PUSH B 
MOVI BX, 'A' 
JMP ERROR 


In a block operation, a comment preceded by two 
semicolons is not saved as part of the expansion 
(1.e€., it will not appear on the listing even under 


aT 
=e 


~LALL). A comment preceded by one semicolon, 
however, will be preserved and appear. in the 
expansion. 


! When an exclamation point is used in an argument, 
the next character is entered literally (i.e., !;3 
and <;> are equivalent). 


c™ 
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NUL 


NUL iS an operator that returns true if its argument 
(a parameter) is null. The remainder of a line 
after NUL is considered to be the argument to NUL. 
The conditional 


IF NUL argument 


is false if, during the expansion, the first 
character of the argument is anything other than a 
semicolon or carriage return. It is recommended 
that testing for null parameters be done using the 
IFB and IFNB conditionals. 


The percent sign is used only in a macro argument. 
%$ converts the expression that follows it (usually a 
Symbol) to a number in the current radix. During 
macro expansion, the number derived from converting 
the expression is substituted for the dummy. Using 
the % special operator allows a macro call by value. 
(Usually, a macro call is a call by reference with 
the text of the macro argument substituting exactly 
for the dummy.) 


The expression following the % must conform to_ the 
same rules as the DS (Define Space) pseudo-op. A 
valid expression returning a non-relocatable 
constant is required. 


EXAMPLE: Normally, LB, the argument to MAKLAB, 
would be substituted for Y, the argument to MACRO, 
aS a string. The % causes LB to be converted to a 
non-relocatable constant which is then substituted 
for Y. Without the % special operator, the result 
of assembly would be ‘Error LB' rather than ‘Error 
i“ 3. StS 


MAKLAB MACRO S 
ERR&Y : DB "Error &Y',0Q 
ENDM 
MAKERR MACRO X 
LB SET 0 
REPT X 
LB SET LB+1 
MAKLAB LB 
ENDM 
ENDM 


When called by MAKERR 3, _ the assembler will 
generate: 


ERR1: DB Terror i? ,0 
ERR2: DB ‘Error 2° ,0 
ERR3: DB "Error 3',0 
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LYPB 


The TYPE operator returns a byte that describes two 
characteristics of its argument: 1) the mode, and 
2) whether it is External or not. The argument’ to 
TYPE may be any expression (string, numeric, 
logical). If the expression is invalid, TYPE 
returns zero. 


The byte that is returned is configured as follows: 


The lower two bits are the mode. If the lower two 
bits are: 


0 the mode is Absolute 

1 the mode is Program Relative 
2 the mode is Data Relative 

3 the mode is Common Relative 


The high bit (80H) is the External bit. If the high 
bit is on, the expression contains an External. If 
the high bit is off, the expression is local (not 
External). 


The Defined bit is 20H. This bit is on if the 
expression is locally defined, and it is off if the 
expression is undefined or external. If neither bit 
is on, the expression is invalid. 


TYPE is usually used inside macros, where an 
argument type may need to be tested ‘to make a 
decision regarding program flow. For example: 


FOO MACRO X 
LOCAL Z 
Z SEt Liee x 


IF Léa 


MACRO-80 ASSEMBLER PAGE 2-33 


2.8 USING 280 PSEUDO-OPS 


When using the MACRO-80 assembler, the following Z80 
pseudo-ops are valid. The function of each pseudo-op is 
equivalent to that of its counterpart. 


Z80 pseudo-op Equivalent pseudo-op 
COND Let 
ENDC ENDIF 
*EJECT PAGE 
DEFB DB 
DEFS DS 
DEFW DW 
DEFM DB 
DEFL SET 
GLOBAL PUBLIC 
EXTERNAL EXTRN 


The formats, where different, conform to the previous 
format. That is, DEFB and DEFW are permitted a list of 
arguments (as are DB and DW), and DEFM is permitted a string 
Or numeric argument (as is DB). 
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2.9 SAMPLE ASSEMBLY 


A>M80 


*EXMPL1, TTY: =EXMPLL 


MAC80 3.2 PAGE A. 
00100 ;CSL3 (P1,P2) 
00200 ;SHIFT Pl LEFT CIRCULARLY 3 BITS 
00300 ;RETURN RESULT IN P2 
00400 ENTRY CSL3 
00450 ;GET VALUE OF FIRST PARAMETER 
00500 CSL3: 
0000' TE 00600 MOV A,M 
0001" 23 00700 INX H 
0002' 66 00800 MOV H,M 
0003' 6F 00900 MOV L,A 
01000 ;SHIFT COUNT 
0004' 06 03 01100 MVI B,3 
0006' AF 01200 LOOP : XRA A 
01300 ;SHIFT LEFT 
0007' Zo 01400 DAD H 
01500 ;ROTATE IN CY BIT 
0008' 17 01600 RAL 
0009' 85 01700 ADD L 
O00A' 6F 01800 MOV L,A 
01900 ;DECREMENT COUNT 
000B' 05 02000 DCR B 
02100 ;ONE MORE TIME 
000C' C2 0006' 02200 JNZ LOOP 
O00F' EB 02300 XCHG 
02400 ;SAVE RESULT IN SECOND PARAMETER 
0010' 43 02500 MOV M,E 
0011" 23 02600 INX H 
0012' TZ 02700 MOV M,D 
0013' CY 02800 RET 
02900 END 
MAC80 3.2 PAGE S 
CSL3 OO00I' LOOP 0006' 


No Fatal error(s) 
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2.10 MACRO-80 ERRORS 


MACRO-80 errors are indicated by a one-character flag in 
column one of the listing file. If a listing file is not 
being printed on the terminal, each erroneous line is also 
printed or displayed on the terminal. Below is a list of 
the MACRO-80 Error Codes: 


A Argument error 
Argument to pseudo-op is not in correct format or 
is out of range (.PAGE 1; .RADIX 1; PUBLIC 1; 
JMPS TOOFAR). 


i Conditional nesting error 
ELSE without IF, ENDIF without IF, two ELSES. on 
one IF. 

D Double Defined symbol 


Reference to a symbol which is multiply defined. 


E External error 
Use of an external illegal in context (e.g., FOO 
SET NAME##; MOVI AX, 2-NAME##) . 


M Multiply Defined symbol 
Definition of a symbol which is multiply defined. 


N Number error 
Error in a number, usually a bad digit (e.g., 8Q). 


O Bad opcode or objectionable syntax 
ENDM, LOCAL outside a block; SET, EQU or MACRO 
without a name; bad syntax in an opcode; or bad 
syntax in an expression (mismatched parenthesis, 
quotes, consecutive operators, etc.). 


P Phase error 
Value of a label or EQU name is different on pass 
hia 

Q Questionable 


Usually means a line is not terminated properly. 
This is a warning error (e.g. MOV AX,BXxX,). 


R Relocation 
Illegal use of relocation in expression, such as 
abs-rel. Data, code and COMMON areas. are 
relocatable. 


U Undefined symbol 
A symbol referenced in an expression is not 
defined. (For certain pseudo-ops, aV error is 
printed on pass 1 and a U on pass 2.) 


(I EEE 
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V Value error 
On pass 1 a pseudo-op which must have its’ value 
known on pass 1 (e.g., .RADIX, .PAGE, DS, IF, IFE, 
etc.), has a value which is’ undefined. If the 
symbol is defined later in the program, a U error 
will not appear on the pass 2 listing. 


Error Messages: 


'No end statement encountered on input file' 
No END statement: either it is missing or it is 
not parsed due to being in a false conditional, 
unterminated IRP/IRPC/REPT block or terminated 
macro. 


'Unterminated conditional' 
At least one conditional is unterminated at the 
end of the file. 


'Unterminated REPT/IRP/IRPC/MACRO' 
At least one block is unterminated. 


[xx] [No] Fatal error(s) [,xx warnings] 
The number of fatal errors and warnings. The 
message is listed on the CRT and in the list file. 


2.11 COMPATIBILITY WITH OTHER ASSEMBLERS 


The SEJECT and STITLE controls are provided for 
compatability with INTEL's ISIS assembler. The dollar sign 
must appear in column 1 only if spaces or tabs separate _ the 
dollar sign from the control word. The control 


SEJECT 


is the same as the MACRO-80 PAGE pseudo-op. 
The control 


STITLE('text') 
is the same as the MACRO-80 SUBTTL <text> pseudo-op. 


The INTEL operands PAGE and INPAGE generate Q errors when 
used with the MACRO-80 CSEG or DSEG pseudo-ops. These 
errors are warnings; the assembler ignores the operands. 


When MACRO-80 is entered, the default for the origin is Code 
Relative 0. 


With the INTEL ISIS assembler, the default is Absolute 0. 
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With MACRO-80, the dollar sign ($) is a defined constant 
that indicates the value of the location counter at the 
Start of the statement. Other assemblers may use a decimal 
point or an asterisk. Other constants are defined by 
MACRO-80 to have the following values: 


A=7 B=0 C=1 D=2 E=3 
H=4 L=5 M=6 SP=6 PSW=6 


2.12 FORMAT OF LISTINGS 


On each page of a MACRO-80 listing, the first two lines have 
the form: 


[TITLE text] M80 3.3 PAGE x[-y] 
[SUBTTL text] 


where: 


1. TITLE text is the text supplied with the TITLE 
pseudo-op, if one was given in the source program. 


2. xX is the major page number, which is incremented 
only when a form feed is encountered in the source 
file. (When using Microsoft's EDIT-80 text editor, 
a form feed is inserted whenever a page mark is 
done.) When the symbol table is being printed, x = 
Se 


3. y is the minor page number, which is incremented 
whenever the .PAGE pseudo-op is encountered in the 
source file, or whenever the current page size has 
been filled. 


4. SUBTTL text is the text supplied with the SUBTTL 
pseudo-op, if one was given in the source program. 


Next, a blank line is printed, followed by the first line of 
output. 


A line of output on a MACRO-80 listing has the following 
form: 


[crf#] [error] loc#m jax: | xexx|... source 


If cross reference information is being output, the first 
item on the line is the cross reference number, followed by 
a tab. 


A one-letter error code followed by a space appears next on 
the line, if the line contains an error. If there is no 
error, a space is printed. If there is no cross'7 reference 
number, the error code column is the first column on the 
listing. 
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The value of the location counter appears next on the line. 
It is a 4-digit hexadecimal number or 6-digit octal number, 
depending on whether the /O or /H switch was given in the 
MACRO-80 command string. 


The character at the end of the location counter value is 
the mode indicator. It will be one of the following 
symbols: 


: Code Relative 

" Data Relative 

! COMMON Relative 
<space> Absolute 

* External 


Next, three spaces are printed followed by the assembled 
code. One-byte values are followed by a space. Two-byte 
values are followed by a mode indicator. Two-byte values 
are printed in the opposite order they are stored in, l.e., 
the high order byte is printed first. Externals are either 
the offset or the value of the pointer to the next External 
in the chain. 


If a line of output on a MACRO-80 listing is from an INCLUDE 
file, the character 'C' is printed after the assembled code 
on that line. If a line of output is part of ae text 
expansion (MACRO, REPT, IRP, IRPC) a plus’ sign '+' is 
printed after the assembled code on that line. 


The remainder of the line contains the line of source code, 
as it was input. 


Example: 
0C49 3A A91Z' C+ LDA LCOUNT 


'C+' indicates this line is from an INCLUDE file and part of 
a macro expansion. 
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2.12.1 Symbol Table Listing 

In the symbol table listing, all the macro names in the 
program are listed alphabetically, followed by all the 
symbols in the program, listed alphabetically. After each 
symbol, a tab is printed, followed by the value of the 
symbol. If the symbol is Public, an I is printed 
immediately after the value. The next character printed 
will be one of the following: 


U Undefined symbol. 

Cc COMMON block name. (The "value" of the 
COMMON block is its length (number of 
bytes) in hexadecimal or octal.) 

* External symbol. 

<space> Absolute value. 

: Program Relative value. 


" Data Relative value. 


! COMMON Relative value. 





CHAPTER 4 


LINK-80 LINKING LOADER 


NOTE 
If you are using the TEKDOS 


operating system, see Appendix 
A for proper command formats. 


4.1 RUNNING LINK-80 
The command to run LINK-80 is 
L80 


LINK-80 returns the prompt "*", indicating it is ready to 
accept commands. 


4.2 COMMAND FORMAT 

Each command to LINK-80 consists of a string of object 

filenames separated by commas. These are the files to be 

loaded by LINK-80. The command format is: 
objfilel,objfile2,...objfilen 

The default extension for all filenames is REL. Command 

lines are supported, that is, the invocation and command may 

be typed on the same line. 

Example: 


L80 MYPROG, YRPROG 
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Any filename in the LINK-80 command string can also _ specify 
a device name. The default device name with the CP/M 
operating system is the currently logged disk. The default 
device with the ISIS-II operating system is disk drive 0. 
The format is: 


devl:objfilel,dev2:objfile2,...devn:objfilen 
The device names are as listed in Section 2.2.1. 
Example: 
L80 MYPROG,A:YRPROG 
After each line is typed, LINK-80 will load the specified 


files. After LINK finishes this process, it will list all 
symbols that remained undefined followed by an asterisk. 


Example: 
*MAIN 
DATA 0100 0200 
SUBRI1* (SUBRL is undefined) 
*SUBRI1 


DATA 0100 0300 


* 


Typically, to execute a MACRO-80 program and _ subroutines, 
the user types the list of filenames followed by /G (begin 
execution). To resolve any external, undefined symbols, you 
can first search your library routines (See Chapter 5, 
LIB-80) by appending the filenames, followed by /S, to the 
loader command string. 


*MYLIB/S Searches MYLIB.REL for unresolved 
global symbols 


*/G Starts execution 


4.2.1 LINK-80 Switches 


A number of switches may be given in the LINK-80 command 
string to specify actions affecting the loading or execution 
of the program(s). Each switch must be preceded by a_ slash 
(/). (With the TEKDOS operating system, switches are 
preceded by hyphens . See Appendix A.) 


~ 
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Switches may be placed wherever applicable in the command 


string: 


: 


At command level. It is possible for a switch to 
be the entire LINK-80 command, or to appear first 
in the command string. For example: 


*/G Tells LINK-80 to begin execution 
of program(s) already loaded 


* /M List all global references 
from program(s) already loaded 


*/P:200,FOO Load FOO, with program area 
beginning at address 200 


Immediately after a filename. An S or N switch may 
refer to only one filename in the command string. 
Therefore, when the S or N switch is required, it 
is placed immediately after that filename, 
regardless of where the filename appears in the 
command string. For example: 


*MYLIB/S ,MYPROG 
Search MYLIB.REL and load necessary 
library modules, then load MYPROG.REL. 


*MYPROG/N ,MYPROG/E 
Load MYPROG.REL, save MYPROG.COM 
on disk and exit LINK-80. 


At the end of the command. string. Any required 
Switches that affect the entire load process may be 
appended at the end of the command. string. For 
example: 


*MYPROG/N ,MYPROG/M/E 


Open a CP/M COM file called 
MYPROG.COM, load MYPROG. REL 
and list all global refer- 
ences. Exit LINK-80 and save 
the COM file. 


MYLIB/S,MYSUB,MYPROG/N,MYPROG/M/G 
Search MYLIB.REL, load and link 
MYSUB.REL and MYPROG.REL, 
open a CP/M COM file 
called MYPROG.COM, list 
all global references, save the 
COM file, and execute MYPROG. 
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The available switches are: 


Switch 


R 


E or E:Name 


G or G:Name 


Action 


Reset. Put loader back in its initial state. 
Use /R if you loaded the wrong file by 
mistake and want to restart. /R takes effect 
as soon as it is encountered in a command 
string. 


Exit LINK-80 and return to the operating 
system. The system library will be searched 
on the current disk to satisfy any existing 
undefined globals. Before exiting, LINK-80 
prints three numbers: the start address, the 
address of the next available byte, and the 
number of 256-byte pages used. The optional 
form E:Name (where Name is a global symbol 
previously defined in one of the modules) 
uses Name for the start address of the 
program. Use /E to load a program and exit 
back to the monitor. 


Start execution of the program as soon as the 
current command line has been interpreted. 
The system library will be searched on the 
current disk to satisfy any existing 
undefined globals if they exist. Before 
execution actually begins, LINK-80 prints 
three numbers and a BEGIN EXECUTION message. 
The three numbers are the start address, the 
address of the next available byte, and_ the 
number of 256-byte pages used. The optional 
form G:Name (where Name is a global symbol 
previously defined in one of the modules) 
uses Name for the start address of the 
program. 


If a <filename>/N is specified, the program 
will be saved on disk under the selected name 
(with a default extension of .COM for CP/M) 
when a /E or /G is done. A jump to the start 
of the program is inserted if needed so the 
program can run properly (at 100H for CP/M). 


c™ 
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P and D 


/P and /D allow the origin(s) to be set for 
the next program loaded. /P and /D take 
effect when seen (not deferred), and they 
have no effect on programs already loaded. 
The form is /P:<address> or /D:<address>, 
where <address> is the desired origin in the 
current typeout radix. (Default radix is 
hex. /O sets radix to octal; /H to hex.) 
LINK-80 does a default /P:<link origin>+3 
(i.e., 103H for CP/M and 4003H for ISIS) to 
leave room for the jump to the start address. 
NOTE: Do not use /P or /D to load programs 
or data into the locations of the loader's 
jump to the start address (100H to 102H for 
CP/M) unless it is to load the start of the 
program there. If programs or data are 
loaded into these locations, the jump will 
not be generated. 





If no /D is given, data areas are loaded 
before program areas for each module. Ifa 
/D is given, all Data and Common areas are 
loaded starting at the data origin and the 
program area at the program origin. Example: 


*/P:200,F00 
Data 200 300 
*/R 


*/P3:200 /D:400,F00 
Data 400 480 
Program 200 280 


List the origin and end of the program and 
data area and all undefined globals as soon 
as the current command line has been 
interpreted. The program information is only 
printed if a /D has been done. Otherwise, 
the program is stored in the data area. 


List the origin and end of the program and 
data area, all defined globals’' and their 
values, and all undefined globals followed by 
an asterisk. The program information is only 
printed if a /D has been done. Otherwise, 
the program is stored in the data area. 


Search the filename immediately preceding the 
/S in the command string to satisfy any 
undefined globals. 
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4.2.2 


CP/M LINK-80 Switches 


The following switches apply to CP/M versions only. 


Xx 


4.263 


LINK 


LINK 


If a filename/N was specified, /X will cause 
the file to be saved in Intel ASCII HEX 
format with an extension of HEX. 


Example: FOO/N/X/E will create an Intel 
ASCII HEX formatted load module named 
FOO. HEX. 


If a filename/N was specified, /Y will create 
a filename.SYM file when /E is entered. This 
file contains the names and addresses of all 
Globals for use with Digital Research's 
Symbolic Debugger, SID and ZSID. 


Example: FOO/N/Y/E creates FOO.COM and 
FOO.SYM. MYPROG/N/X/Y/E creates MYPROG. HEX 
and MYPROG.SYM. 


Sample Links 


AND GO 


A>L80 


*EXAMPL, EXMPL1/G 
DATA 3000 30AC 
[304F 30AC 49] 
[BEGIN EXECUTION] 


1792 14336 
14336 -16383 
-16383 14 
14 Liz 
112 896 
A> 
AND SAVE 
A>L80 
*EXAMPL, EXAMPL1, EXAM/N/E 
DATA 3000 30AC 
[304F 30AC 49] 
A> 


Loads and links EXAMPL.REL, EXMPL1.REL and creates 


EXAM.COM. 


f™ 
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4.3 FORMAT OF LINK COMPATIBLE OBJECT FILES 


NOTE 


Section 4.3 is reference 
material for users who wish to 
Know the load format of 
LINK-80 relocatable object 
files. Most users will want 
to skip this section, as it 
does not contain material 
necesSary to the operation of 
the package. 


LINK-compatible object files consist of a bit stream. 
Individual fields within the bit stream are not aligned on 
byte boundaries, except as noted below. Use of a bit stream 
for relocatable object files keeps the size of object files 
to a minimum, thereby decreasing the number of disk 
reads/writes. 


There are two basic types of load items: Absolute and 
Relocatable. The first bit of an item indicates one of 
these two types. If the first bit is a 0, the following 8 
bits are loaded as an absolute byte. If the first bit is a 
1, the next 2 bits are used to indicate one of four types of 
relocatable items: 


00 Special LINK item (see below). 


O01 Program Relative. Load the following 16 bits 
after adding the current Program base. 


10 Data Relative. Load the following 16 bits after 
adding the current Data base. 


Ll Common Relative. Load the following 16 bits 
after adding the current Common base. 


Special LINK items consist of the bit stream 100 followed 
by: 

a four-bit control field 

an optional A field consisting of a two-bit 


address type that is the same as the two-bit 
field above except 00 specifies absolute address 


an optional B field consisting of 3 bits’ that 
give a symbol length and up to 8 bits for each 
Character of the symbol 
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A general representation of a special LINK item is: 





1 00 xxxx yy nn ZZz + characters of symbol name 
A field B field 

XXXX Four-bit control field (0-15 below) 

yV Two-bit address type field 

nn Sixteen-bit value 

ZZZ Three-bit symbol length field 


The following special types have a B-field only: 


& WN - © 


Entry symbol (name for search) 
Select COMMON block 

Program name 

Request library search 
Extension LINK items (see below) 


The following special LINK items have both an A field and a 


B field: 


5 
6 


7 


Define COMMON size 

Chain external (A is head of address chain, B is 
name of external symbol) 

Define entry point (A is address, B is name) 


The following special LINK items have an A field only: 


8 


13 
14 


External - offset. Used for JMP and CALL to 
externals 
External + offset. The A value will be added to 
the two bytes starting at the current location 
counter immediately before execution. 

Define size of Data area (A is size) 

Set loading location counter to A 
Chain address. A is head of chain, replace all 
entries in chain with current location counter. 
The last entry in the chain has an address field 
of absolute zero. 

Define program size (A is size) 

End program (forces to byte boundary) 
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The following special Link item has neither an A nor a B 
field: 


LS End file 


An Extension LINK item follows the general format of a 
B-field-only special LINK item, but contents of the B-field 
are not a symbol name. Instead, the symbol area contains 
One character to identify the type of Extension LINK item, 
followed by from 1 to | characters of additional 
information. 


Thus, every Extension LINK item has the format: 


1 00 0100 zzz i jjj53533 


where 
ZZZ may be any three bit integer (with 000 
representing 8), 
i. is an eight bit Extension LINK item type 
identifier, and 
333354353 are ZZZ—-1 eight bit characters of 


information whose significance depends on i 
At present, there is only one Extension LINK item: 


= X'35' COBOL overlay segment sentinel 


1 = 
ZZZ = 010 (binary) 
5 = COBOL segment number -49 (decimal) 


When the overlay segment sentinel is encountered by the 
linker, the current overlay segment number is set to the 
value of jt49. If the previously existing segment 
number was non-zero anda /N switch is in effect, the 
data area is written to disk in a file whose name is the 
current program name and whose extension is Vnn, where 
nn are the two hexadecimal digits representing the 
number j3+49 (decimal). 


—————————— 
EI 
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4.4 LINK-80 ERROR MESSAGES 
LINK-80 has the following error messages: 


?No Start Address A /G switch was issued, but no main 
program had been loaded. 


?Loading Error The last file given for input was not a 

properly formatted LINK-80 object file. 
2O0ut of Memory Not enough memory to load program. 
?Command Error Unrecognizable LINK-80 command. 


?<file> Not Found <file>, as given in the command. string, 
did not exist. 


$2nd COMMON Larger /XXXXXX/ 
The first definition of COMMON block 
/¥XXXXX/ was not the largest definition. 
Reorder module loading sequence or 
change COMMON block definitions. 


$Mult. Def. Global YYYYYY 
More than one definition for the global 
(internal) symbol YYYYYY was encountered 
during the loading process. 


Data ,Public = <symbol name> (xxxx) 
,External = <symbol name> (xxxx) 
A /D or /P will cause already loaded 
data to be destroyed. 


este ack | tt Area ,Start = XxXxx 


?Intersecting } Program| Area 
Data 
The program and data area intersect and 
an address or external chain entry is in 
this intersection. The final value 
cannot be converted to a current value 
since it is in the area intersection. 


?Start Symbol - <name> - Undefined 
After a /E: or /G: is given, the 
symbol specified was not defined. 
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Below 


vr" seat or bt Loader Memory, Move Anyway (Y or N)? 


After a /E or /G was given, either’ the 
data or program area has an origin or 
top which . lies outside loader memory 
(i.e., loader origin to top of memory). 
If a Y <cr> is given, LINK-80 will move 
the area and continue. If anything else 
is given, LINK-80 will exit. In either 
case, if a /N was given, the image will 
already have been saved. 


?Can't Save Object File 
A disk error occurred when the file was 
being saved. 


4.5 PROGRAM BREAK INFORMATION 


LINK-80 stores the address of the first free location in a 
global symbol called SMEMRY if that symbol has been defined 
by a program loaded. S$MEMRY is set to the top of the data 
area +l. 


NOTE 


If /D is given and the data 
Origin is less than the 
program area, the user must be 
sure there is enough room to 
keep the program from being 
destroyed. This is 
particularly true with the 
disk driver for FORTRAN-80 
which uses $MEMRY to allocate 
disk buffers and FCB's. 











APPENDIX A 


TEKDOS Operating System 


The command formats for MACRO-80, LINK-80 and CREF-80 differ 
slightly under the TEKDOS operating system. 


A.1 TEKDOS COMMAND FILES 


The files F80, M80, and C80 are actually TEKDOS command 
files for the compiler, assembler, loader, and cross 
reference programs, respectively. These command files’ set 
the emulation mode to 0 and select the 2-80 assembler 
processor (see TEKDOS documentation), then execute the 
appropriate program file. You will note that all of these 
command files are set up to execute the Microsoft programs 
from drive 1. LINK-80 will also look for the library 
(FORLIB) on drive 1. If you wish to execute any of this 
software from drive 0, the command file must be edited and 
LINK-80 should be given an explicit library search directive 
"FORLIB-S". (See Section 4.2.1 of this manual.) 


The M80 assembler accepts command lines only. A prompt is 
not displayed and interactive commands are not accepted. 
Commands have the same format as TEKDOS assembler commands; 
i.e., three filename or device name parameters plus optional 
Switches. 


M80 [objfile] [lstfile] sourcefile [swl] [sw2...] 


The object and listing file parameters are optional. These 
files will not be created if the parameters are omitted, 
however any error messages will still be displayed on the 
console. The available switches are as described in Chapter 
2 of this manual. except that the switches are delimited by 
commas or spaces instead of slashes. 
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A.3 CREF-80 
The form of commands to CREF80 is: 
C80 lstfile sourcefile 


Both filename parameters are required. The sourcefile 
parameter is always the name of a CREF80 file created during 
assembly, by use of the C switch. 


Example: 
Create a CREF80 file using MACRO-80: 
M80 ,, TSTCRF TSTMAC C 
Create a cross reference listing from the CREF80 file: 


C80 TSTLST TSTCRF 


A.4 LINK-80 


With TEKDOS, the LINK-80 loader accepts interactive commands 
only. Command lines are not supported. 


When LINK-80 is invoked, and whenever it is waiting for 
input, it will prompt with an asterisk. Commands are lists 
of filenames and/or devices separated by commas or _ spaces 
and optionally interspersed with switches. The input to 
LINK-80 must be Microsoft relocatable object code (not the 
same as TEKDOS loader format). 


Switches to LINK-80 are delimited by hyphens under TEKDOS, 
instead of slashes. All LINK-80 switches (as documented in 
Chapter 3) are supported, except "G" and "N", which are not 
implemented at this time. 


Examples: 


1. Assemble a MACRO-80 program named XTEST, creating 
an object file called XREL and a listing file 
called XLST: 


>M80 XREL XLST XTEST 
2. Load XTEST and save the loaded module: 


>L80 

*XREL—-E 

[O4AD 22B8] 
*DOS*ERROR 46 

L80 TERMINATED 

>M XMOD 400 22B8 O4AD 
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Note that "-E" exits via an error message due to execution 
of a Halt instruction. The memory image is intact, however, 
and the "Module" command may be used to save it. Once a 
program is saved in module format, it may then be executed 
directly without going through LINK-80 again. 


The bracketed numbers printed by LINK-80 before exiting are 
the entry point address and the highest address loaded, 
respectively. The loader default is to begin loading at 
400H. However, the loader also places a jump to the start 
address in location 0, thereby allowing execution to begin 
at Q. The memory locations between 0003 and 0400H are 
reserved for SRB's and I/O buffers at runtime. 
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Microsoft 
Software Problem Report 


Use this form to report errors or problems in: [_] FORTRAN-80 
[__] COBOL-80 
[_] MACRO-80 
{_] LINK-80 
Release (or version) number: 
Date 


Report only one problem per form. 


Describe your hardware and operating system: 





Please supply a concise description of the problem and the 
circumstances surrounding its occurrence. If possible, reduce 
the problem to a simple test case. Otherwise, include all 
programs and data in machine readable fcrm (preferably on a 
diskette). If a patch or interim solution is being used, 
Please describe it. 


This form may also be used to describe suggested enhancements 
to Microsoft software. 


Problem Description: 


-Over= 


Did you find errors in the documentation supplied with the 
software? If so, please include page numbers and describe: 


Fill in the following information before returning this form: 


Name Phone 





Organization 
Address Catv State Zip 
Return form to: Microsoft 


10800 NE Eighth, Suite 8:19 
Bellevue, WA 98004 
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ED USER'S MANUAL 


L« ED TUTORIAL 
1.1. Introduction to ED. 


ED is the context editor for CP/M, and is used to create 
and alter CP/M source files. ED is initiated in CP/M by 


typing 


<filename> 
ED 
<filename>.<filetype> 


In general, ED reads segments of the source file given by 
<filename> or <filename> . <filetype> into central memory, 
where the file is manipulated by the operator, and subse- 
quently written back to disk after alterations. If the 
source file does not exist before editing, it is created by 
ED and initialized to empty. The overall operation of ED 
is shown in Figure l. 


1.2. ED Operation 


ED operates upon the source file, denoted in Figure l 
by x.y, and passes all text through a memory buffer where 
the text can be viewed or altered (the number of lines which 
can be maintained in the memory buffer varies with the line 
length, but has a total capacity of about 6000 characters 
in a 16K CP/M system). Text material which has been edited 
is written onto a temporary work file under command of the 
Operator. Upon termination of the edit, the memory buffer 
is written to the temporary file, followed by any remaining 
(unread) text in the source file. The name of the original 
file is changed from x.y to x.BAK so that the most recent 
previously edited source file can be reclaimed if necessary 
(see the CP/M commands ERASE and RENAME). The temporary 
file is then changed from x.$$$ to x.y which becomes the 
resulting edited file. 

The memory buffer is logically between the source file 
and working file as shown in Figure 2. 


1.3. Text Transfer Functions 


Given that n is an integer value in the range 0 through 
65535, the following ED commands transfer lines of text 
from the source file through the memory buffer to the tem- 
porary (and eventually final) file: 








Figure 1. Overall ED Operation 
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Note: the ED program accepts both lower and upper case ASCII 
characters as input from the console. Single letter commands 
can be typed in either case. The U command can be issued to 

cause ED to translate lower case alphabetics to upper case as 
characters are filled to the memory buffer from the console. 

Characters are echoed as typed without translation, however. 
The -U command causes ED to revert to "no translation" mode. 

ED starts with an assumed -U in effect. 





Figure 2. Memory Buffer Organization 
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Figure 3. Logical Organization of Memory Buffer 
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nA<cr>* append the next n unprocessed source 
lines from the source file at SP to 
the end of the memory buffer at MP. 


Increment SP and MP by n. 


nW<cr> - write the first n lines of the memory 
buffer to the temporary file free space. 
Shift the remaining lines n+l through 
MP to the top of the memory buffer. 
Increment TP by n. 


E<xcr> - end the edit. Copy all buffered text 
to temporary file, and copy all un- 
processed source lines to the temporary 
file. Rename files as described 
previously. 


H<cr> - move to head of new file by performing 
automatic E command. Temporary file 
becomes the new source file, the memory 
buffer is emptied, and a new temporary 
file is created (equivalent to issuing 
an E command, followed by a reinvocation 
of ED using x.y as the file to edit). 


O<cr> - return to original file. The memory 
buffer is emptied, the temporary file 
id deleted, and the SP is returned to 
position 1 of the source file. The 
effects of the previous editing commands 
are thus nullified. 


Q<cr> - quit edit with no file alterations, 
return to CP/M. 


There are a number of special cases to consider. If the 
integer n is omitted in any ED command where an integer is 
allowed, then 1 is assumed. Thus, the commands A and W append 
One line and write 1 line, respectively. In addition, if a 
pound sign (#) is given in the place of n, then the integer 
65535 is assumed (tne largest value for n which is allowed). 
Since most reasonably sized source files can be contained 
entirely in the memory buffer, the command #A is often issued 
at the beginning of the edit to read the entire source file 
to memory. Similarly, the command #W writes the entire buffer 
to the temporary file. Two special forms of the A and W 


*<cr> represents the carriage-return key 


commands are provided as a convenience. The command OA fills 
the current memory buffer to at least half-full, while OW 
writes lines until the buffer is at least half empty. It 
should also be noted that an error is issued if the memory 
buffer size is exceded. The operator may then enter any 
command (such as W) which does not increase memory require- 
ments. The remainder of any partial line read during the 
overflow will be brought into memory on the next successful 
append. 


1.4. Memory Buffer Organization 


The memory buffer can be considered a sequence of source 
lines brought in with the A command from a source file. The 
memory buffer has an associated (imaginary) character pointer 
CP which moves throughout the memory buffer under command of 
the operator. The memory buffer appears logically as shown 
in Figure 3 where the dashes represent characters of the 
source line of indefinite length, terminated by carrigage- 
return (<cr>) and line-feed (<lf>) characters, and 
represents the imaginary character pointer. Note that the 
CP is always located ahead of the first character of the 
first line, behind the last character of the last line, or 
between two characters. The current line CL is the source 
line which contains the CP. 





1.5. Memory Buffer Operation 


Upon initiation of ED, the memory buffer is empty (ie, 
CP is both ahead and behind the first and last character). 
The operator may either append lines (A command) from the 
source file, or enter the lines directiy from the console 
with the insert command 


L<Cr> 


ED then accepts any number of input lines, where each line 
terminates with a <cr> (the <lf> is supplied automatically), 
until a control-z (denoted by tz is typed by the operator. 
The CP is positioned after the last character entered. The 
sequence 


i<cr> 

NOW IS THE<cr> 
TIME FOR<cr> 

ALL GOOD MEN<cr> 
4 Z 


leaves the memory buffer as shown below 








NOW IS THE<cr><lf> 
TIME FOR<cr><lf> 


ALL GOOD MEN<cr><lf> * 


Various commands can then be issued which manipulate the CP 

or display source text in the vicinity of the CP. The 
commands shown below with a preceding n indicate that an 
optional unsigned value can be specified. When preceded by 

+, the command can be unsigned, or have an optional preceding 
plus or minus sign. As before, the pound sign (#) is replaced 
by 65535. If an integer nis optional, but not supplied, 

then n=l is assumed. Finally, if a plus sign is optional, 

but none is specified, then + is assumed. 


+B<cr> - move CP to beginning of memory buffer 
if +, and to bottom if -. 


+nC<cr> - move CP by tn characters (toward front 
of buffer if +), counting the <cr><lf> 
as two distinct characters 


tnD<cr> - delete n characters ahead of CP if plus 
and behind CP if minus. 


tnK<cr> - kill (ie remove) tn lines of source text 
using CP as the current reference. If 
CP is not at the beginning of the current 
line when K is issuec, then the charac- 
ters before CP remain if + is specified, 
while the characters after CP remain if - 
is given in the command. 


tnL<cr> - if n=0 then move CP to the beginning of 
the current line (if it is not already 
there) if n4#0 then first move the CP to 
the beginning of the current line, and 
then move it to the beginning of the 
line which is n lines down (if +) or up 
(if -). The CP will stop at the top or 
bottom of the memory buffer if too large 
a value of nis specified. 


+nT<cr> - If n=0 then type the contents of the 
current line up to CP. If n=l then 
type the contents of the current line 
from CP to the end of the line. If 
n>l then type the current line along 
with n-l lines which follow, if + 
is specified. Similarly, if n>l and 
- is given, type the previous n lines, 
up to the CP. The break key can be 
depressed to abort long type-outs. 


tn<cr> - equivalent to +tnLT, which moves up or 
down and types a single line 


1.6. Command Strings 


Any number of commands can be typed contiguously (up to 
the capacity of the CP/M console buffer), and are executed 
only after the <cr> is typed. Thus, the operator may use 
the CP/M console command functions to manipulate the input 
command: 


Ru bout remove the last character 
Contro1-U delete the entire line 
Control-C re-initialize the CP/M System 
Control-E return carriage for long lines 


without transmitting buffer 
(max 128 chars) 


Suppose the memory buffer contains the characters shown 
in the previous section, with the CP following the last 
character of the buffer. The command strings shown below 
produce the results shown to the right 


Command String Effect Resulting Memory Buffer 
1. B2T<cr> move to beginning NOW IS THE<cr><lf> 
of buffer and type ee TIME FOR<cr><1£> 
2 lines: 
"NOW IS THE ALL GOOD MEN<cr><lf> 
TIME FOR" 
Ze SCOLScr> move CP 5 charac- NOW T ep) ® THE<cr><lf> 
ters and type the cP 
beginning of the 
line 
"NOW I" 














Cee 4 a! US op a move two lines down NOW IS THE<cr><l1f> eg 
and type previous TIME FOR<cr><1£> 


line 
"TIME FOR" - ; ALL GOOD MEN<cr><lf> 
4. -L#K<cr> move up one line, NOW IS sarees. 
delte 65535 lines 
which follow 
Ss: ) ere insert two lines NOW IS THE<cr><lf> 
TIME TO<cr> of text 
INSERT<cr> TIME TO<cr><lf> 


tz ENSENE SP SUE eo) 


6. =2L4T<cr> move up two lines, NOW IS apiic ath aaaey Co 


and type 65535 
lines ahead of CP TIME TO<cr><1f> 


"NOW IS THE" INSERT<cr><lf> 
is = <e@ye> move down one line NOW IS THE<cr><lf> 
and type one line 
"TNSERT" TIME TO<cr><lf> ep) 
INSERT<cr><lf> a 


1.7. Text Search and Alteration 


ED also has a command which locates strings within the 
memory buffer. The command takes the form 


F <Cr> 
nN oh ake aecstiagt "2 Ag 


where c, through cy represent the Characters to match followed 
by either a <cr> or control -z . ED starts at the current 
position of CP and attempts to match all k characters. The 
match is attempted n times, and if successful, the CP is 

moved directly after the character c,. If the n matches are 
not successful, the CP is not moved from its initial position. 
Search strings can include tl (control-1l), which is replaced 
by the pair of symbols <cr><lf>. 





*The control-z is used if additional commands will be typed 
following the tz. 


The following commands illustrate the use of the F 
command : 





Command String Effect Resulting Memory Buffer 
1. B#T<cr> move to beginning (ep) NOW IS THE<cr><lf> 
and type entire 
bist far TIME FOR<cr><lf> 
ALL GOOD MEN<cr><l£> 
2. FS T<cr> find the end of NOW IS B(eole ee 
the string "S T" 
36-0 -FI+20TT find the next "I" NOW IS THE<cr><lf> 
and type to the 
CP then type the Tr ep)" FOR<cr><lf> 
remainder of the ALL GOOD MEN<cr><lf> 
current line: 
"TTME FOR" 


An abbreviated form of the insert command is also allowed, 
which is often used in conjunction with the F command to make 
Simple textual changes. The form is: 


1 s¢ C2 4Z or 
n 


1°9° ee 


1; ¢.¢ 


e® @ @ CG <cr> 
ae n 


where c) through c, are characters to insert. If the inser- 
tion string is terminated by a tz, the characters c, through 
Cy, are inserted directly following the CP, and the CP is 
moved directly after character c,. The action is the same 
if the command is followed by a <cr> except that a <cr><lf> 
is automatically inserted into the text following character 
Cn: Consider the following command sequences as examples 

of the F and I commands: 





Command String Effect Resulting Memory Buffer 
BITHIS IS tz<cr> Insert "THIS IS " THIS IS NOW THE <cr><lf> 
at the beginning 
of the text 


TIME FOR<cr><lf> 
ALL GOOD MEN<cr><1f> 














FTIME*Z2-4DIPLACEt z<cr> THIS IS NOW THE<cr><lf> 


find "TIME" and delete Pe hp ta aie ala 
it; then insert "PLACE" ALL GOOD MEN<cr><lf£> 
3FOt+Z-3D5DICHANGES*t<cr> THIS IS NOW THE <cr><lf> 


find third occurrence PLACE FOR<cr><1f> 

of "O" (ie the second ALL CHANGES Cp sia 
"O" in GOOD), delete 

previous 3 characters; 

then insert "CHANGES" 


-8CISOURCE<cr> move back 8 characters THIS IS NOW THE<cr><lf> 
and insert the line PLACE FOR<cr><1£> 


"SOURCE<cr><lf£>" 
ALL SOURCE<cr><lf> 


icelat pe ees 


ED also provides a single command which combines the F and 
I commands to perform simple string substitutions. The command 
takes the form 


<cr> 
ns Cp Core C, t2 aa,...d, { is 


and has exactly the same effect as applying the command string 


<cr> 
F Cp Core eC, tz kDId,d,-.-d, $e 


a total of n times. That is, ED searches the memory buffer 
starting at the current position of CP and successively sub- 
stitutes the second string for the first string until the 
end of buffer, or until the substitution has been performed 
n times. 

As a convenience, a command similar to F is provided by 
ED which automatically appends and writes lines as the search 
proceeds. The form is 


cr 
nN ed ae fs} 


which searches the entire source file for the nth occurrence 
of the string cjc9...c, (recall that F fails if the string 
cannot be found in the current buffer). The operation of the 


10 


iW command is precisely the same as F except in the case that 
the string cannot be found within the current memory buffer. 
In this case, the entire memory contents is written (ie, an 
automatic #W is issued). Input lines are then read until 
the buffer is at least half full, or the entire source file 
is exhausted. The search continues in this manner until the 
string has been found n times, or until the source file has 
been completely transferred to the temporary file. 

A final line editing function, called the juxtaposition 
command takes the form 


<cy> 
nJ C1 Ca++, tz djdj---d tz Sie oe oe es, 


with the following action applied n times to the memory buffer: 
search from the current CP for the next occurrence of the 
String ¢C)C9...c If found, insert the string djd9..-,d,, 

and move CP to ollow dm: Then delete all characters following 
CP up to (but not including) the string e), 1On7022€ leaving 

CP directly after d,. If e1,e9,...¢e anor he fond, then 

no deletion is made. If the current line is 


én) 0" IS THE TIME<cr><lf> 


Then the command 
JW tZWHATtztl<cr> 
Results in 


NOW WHAT (cpl <r 1 t> 


(Recall that tl represents the pair <cr><l1f> in search and 
substitute strings). 

It should be noted that the number of characters allowed 
by ED in the F,S,N, and J commands is limited to 100 symbols. 


1.8. Source Libraries 
ED also allows the inclusion of source libraries during 


the editing process with the R command. The form of this 
command is 


ak 














R ff, 


a ae or 
n 


R f£,f£,--f£,<er? 


where f,f9.-.f, is the name of a source file on the disk with 
as assumed filetype of 'LIB'. ED reads the specified file, 
and places the characters into the memory buffer after CP, 
in a manner similar to the I command. Thus, if the command 


RMACRO<cr> 


is issued by the operator, ED reads from the file MACRO.LIB 
until the end-of-file, and automatically inserts the charac- 
ters into the memory buffer. 


1.9. Repetitive Command Execution 


The macro command M allows the ED user to group ED com- 
mands together for repeated evaluation. The M command takes 


the form: 
<cr> 
nM Cy Core + Cy eng 


where C)C9...c, represent a string of ED commands, not inclu- 


ding another M command. ED executes the command string n 
times if n>l. If n=0 or 1, the command string is executed 
repetitively until an error condition is encountered (e.g., 
the end of the memory buffer is reached with an F command). 

As an example, the following macro changes all occur- 
rences of GAMMA to DELTA within the current buffer, and 
types each line which is changed: 


MF GAMMA+z-5DIDELTAt¢z0TT<cr> 


or equivalently 


MSGAMMAtZDELTAtzOTT<cr> 
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c™ 
2. ED ERROR CONDITIONS 


On error conditions, ED prints the last character read 
before the error, along with an error indicator: 


? unrecognized command 


> memory buffer full (use one of 
the commands D,K,N,S, or W to 
remove characters), F,N, or S 
strings too long. 


i Cannot apply command the number 
of times specified (e.g., in 
F command) 


O cannot open LIB file in R 
command 


Cyclic redundancy check (CRC) information is written with 
each output record under CP/M in order to detect errors on 
subsequent read operations. If a CRC error is detected, CP/M 
will type 


f~ PERM ERR DISK d 


where d is the currently selected drive (A,B,...). The oper- 
ator can choose to ignore the error by typing any character 
at the console (in this case, the memory buffer data should 
be examined to see if it was incorrectly read), or the user 
can reset the system and reclaim the backup file, if it 
exists. The file can be reclaimed by first typing the con- 
tents of the BAK file to ensure that it contains the proper 
information: 


TYPE x. BAK<cr> 


where x is the file being edited. Then remove the primary 
file: 


ERA x.y<cr> 
and rename the BAK file: 
REN xX. y=x. BAK<cr> 


i’ The file can then be re-edited, starting with the previous 
version. 
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3. CONTROL CHARACTERS AND COMMANDS 


The following table summarizes the control characters 
and commands available in ED: 


Control Character Function 
tC system reboot 
te physical <cr><lf> (not 
actually entered in 
command) 
ae 0 logical tab (cols 1,8, 
i a | 
rE logical <cr><l1f> in 
search and substitute 
strings 
4u line delete 
NZ, string terminator 
rubout character delete 
break discontinue command 


(e.g., stop typing) 
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Command Function 
nA append lines 
+B begin bottom of buffer 
snc move character positions 
+nD delete characters 
E end edit and close files 


(normal end) 


nF find string 
H end edit, clcse and reopen 
files 
I insert characters 
nJ place strings in juxtaposition 
+nK kill lines 
+nL move down/up lines 
O) nM macro definition 
nN find next occurrence with 
autoscan 
O return to original file 
+nP move and print pages 


quit with no file changes 


R read library file 
ns substitute strings 
+nT type lines 


translate lower to upper case if U, 


iz no translation if -U 
nw write lines 

nZ sleep 
+n<cr> move and type (+tnLT) 


Lo 






Appendix A: ED 1.4 Enhancements 


The ED context editor contains a number of commands which enhance its 
usefulness in text editing. The improvements are found in the addition of line numbers, 
free space interrogation, and improved error reporting. 


The context editor issued with CP/M 1.4 produces absolute line number prefixes 
when the "V" (Verify Line Numbers) command is issued. Following the V command, 
the line number is displayed ahead of each line in the format: 


hnnnnn: 


where nnnnn is an absolute line number in the range 1 to 65535. If the memory buffer 
is empty, or if the current line is at the end of the memory buffer, then nnnnn appears 
as 5 blanks. 


The user may reference an absolute line number by preceding any command by 
a number followed by a colon, in the same format as the line number display. In this 
case, the ED program moves the current line reference to the absolute line number, 
if the line exists in the current memory buffer. Thus, the command 


345:T 


is interpreted as "move to absolute line 345, and type the line." Note that absolute 
line numbers are produced only during the editing process, and are not recorded with 
the file. In particular, the line numbers will change following a deleted or expanded 
section of text. 


The user may also reference an absolute line number as a backward or forward 
distance from the current line by preceding the absolute line number by a colon. Thus, 
the command 


:400T 


is interpreted as "type from the current line number through the line whose absolute 
number is 499." Combining the two line reference forms, the command 


345 ::400T 
for example, is interpreted as "move to absolute line 345, then type through absolute 
line 490." Note that absolute line references of this sort can precede any of the 


standard ED commands. 


A special case of the V command, "9V", prints the memory buffer statistics in 
the form: 


free/total 


where "free" is the number of free bytes in the memory buffer (in decimal), and "total" 
is the size of the memory buffer. 


ED 1.4 also includes a "block move" facility implemented through the "X" (Xfer) 
command. The form 


nX 
transfers the next n lines from the current line to a temporary file called 


X$$$$$$$.LIB 


which is active only during the editing process. In general, the user can reposition 
the current line reference to any portion of the source file and transfer lines to the 
temporary file. The transferred line accumulate one after another in this file, and 
ean be retrieved by simply typing: 


R 


which is the trivial case of the library read command. In this case, the entire 
transferred set of lines is read into the memory buffer. Note that the X command 
does not remove the transferred lines from the memory buffer, although a K command 
ean be used directly after the X, and the R command does not empty the transferred 
line file. That is, given that a set of lines has been transferred with the X command, 
they can be re-read any number of times back into the source file. The command 


AX 
is provided, however, to empty the transferred line file. 

Note that upon normal completion of the ED program through Q or E, the 
temporary LIB file is removed. If ED is aborted through ctl-C, the LIB file will exist 
if lines have been transferred, but will generally be empty (a subsequent ED invocation 
will erase the temporary file). 

Due to common typographical errors, ED 1.4 requires several potentially disas- 
terous commands to be typed as single letters, rather than in composite commands. 
The commands 

E (end), H (head), O (original), Q (quit) 
must be typed as single letter commands. 


ED 1.4 also prints error messages in the form 


BREAK "x" AT ¢ 


where x is the error character, and c is the command where the error occurred. 
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CP/M Dynamic Debugging Tool (DDT) 


User “s Guide 


I. Introduction. 


The DDI program allows dynamic interactive testing and debugging of 
programs generated in the CP/M environment. The debugger is initiated by 
typing one of the following commands at the CP/M Console Command level 


DDT 
DDI filename .HEX 
DDI filename.COM 


where “filename” is the name of the program to be loaded and tested. In both 
cases, the DDI program is brought into main memory in the place of the Console 
Command Processor (refer to the CP/M Interface Guide for standard memory 
organization), and thus reSides directly below the Basic Disk Operating System 
portion of CP/M. The BDOS starting address, which is located in the address 
field of the JMP instruction at location 5H, is altered to reflect the reduced 
Transient Program Area size. 


The second and third forms of the DDI command shown above perform the same 
actions as the first, except there is a subsequent automatic load of the 
specified HEX or COM file. The action is identical to the sequence of 
commands 


DDI 
Ifilename HEX or Ifilename.COM 
R 


where the I and R commands set up and read the specified program to test (see 
the explanation of the I and R commands below for exact details). 


Upon initiation, DDI prints a sign-on message in the format 
nnK DDI-s VER mm 


where nn is the memory size (which must match the CP/M system being used), s 
is the hardware system which is assumed, corresponding to the codes 


- Digital Research standard version 
- MDS version 

IMSAI standard version 

- Omron systems 

- Digital Systems standard version 


On ZYO 
i 


and mm is the revision numer. 


Following the sign on message, DDI prompts the operator with the character 
"—""and waits for input commands from the console. The operator can type any 
of several single character commands, terminated by a carriage return to 
execute the command. Each line of input can be line-edited using the standard 
CP/M controls 


rubout remove the last character typed 
ctl-U remove the entire line, ready for re-typing 
ctl-—C system reboot 


Any command can be up to 32 characters in length (an automatic carriage return 
1S inserted as the 33rd character), where the first character determines the 
command type 


enter assemdly language memonics with operands 
display memory in hexadecimal and ASCII 

fill memory with constant data 

begin execution with optional breakpoints 

set up a standard input file control block 

list memory uSing assembler mnemonics 

move a memory segment from source to destination 
read program for subsequent testing 

substitute memory values 

trace program execution 

untraced program monitoring 

examine and optionally alter the CPU state 


XCGHHNDWAEMrHHDDU Pp 


The cammand character, in some cases, is followed by zero, one, two, or three 
hexadecimal values which are separated by commas or single blank characters. 
All DDI numeric output is in hexadecimal form. In all cases, the commands are 
not executed until the carriage return is typed at the end of the command. 


At any point in the debug run, the operator can stop execution of DDT 
using either a ctl-C or G@ (jmp to location @@@@H), and save the current 
memory image uSing a SAVE command of the form 


SAVE n filename.COM 


where n is the number of pages (256 byte blocks) to be saved on disk. The 
number of blocks can be determined by taking the high order byte of the top 
load address amd converting this number to decimal. For example, if the 
highest address in the Transient Program Area is 1234H then the number of 
pages is 12H, or 18 in decimal. Thus the operator could type a ctl-C during 
the debug run, returning to the Console Processor level, followed by 


SAVE 18 X.COM 
The memory image is saved as X.COM on the diskette, and can be directly 


executed by simply typing the name X. If further testing is required, the 
memory image can be recalled by typing 


DDI X.COM 


which reloads previously saved program from loaction 1@@H through page 18 
(12FFH). The machine state is not a part of the COM file, and thus the 
program must be restarted from the beginning in order to properly test it. 


II. DDI COMMANDS. 


The individual commands are given below in some detail. In each case, the 
operator must wait for the prompt character (-) before entering the command. 
If control is passed to a program under test, and the program has not reached 
a breakpoint, control can be returned to DDI by executing a RST 7 from the 
front panel (note that the rubout key should be used instead if the program is 
executing a T or U command). In the explanation of each command, the command 
letter is shown in some cases with numbers separated by canmas, where the 
numers are represented by lower case letters. These numbers are always 
assumed to be in a hexadecimal radix, and from one to four digits in length 
(longer numbers will be automatically truncated on the right). 


Many of the commands operate upon a "CPU state" which corresponds to the 
program under test. The CPU state holds the registers of the program being 
debugged, and initially contains zeroes for all registers and flags except for 
the program counter (P) and stack pointer (S), which default to 1@00H. ‘The 
program counter is subsequently set to the starting address given in the last 
record of a HEX file if a file of this form is loaded (see the I and R 
commands) . 


1. The A (Assemble) Command. DDI allows inline assembly language to be 
inserted into the current memory image using the A command which takes the 
form 

As 


where S iS the hexadecimal starting address for the inline assembly. DDT 
prompts the console with the address of the next instruction to fill, and 
reads the console, looking for assembly language mnemonics (see the Intel 8080 
Assembly Language Reference Card for a list of mmemonics), followed by 
register references and operands in absolute hexadecimal form. Each sucessive 
load address is printed before reading the console. The A command terminates 
when the first empty line is input from the console. 


Upon campletion of assembly language input, the operator can review the 
memory segment using the DDI disassembler (see the L command). 


Note that the assembler/disassembler portion of DDI can be overlayed by 
the transient program being tested, in which case the DDI program responds 
with an error condition when the A and L commands are used (refer to Section 
IV). 





———— 





2. The D (Display) Command. The D command allows the operator to view 
the contents of memory in hexadecimal and ASCII formats. The forms are 


D 
Ds 
Ds ,f 


In the first case, memory is displayed from the current display address 
(initially 19@H), and continues for 16 display lines. Each display line takes 
the form shown below 


aaaa bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb bb cccccccccccccccce 


where aaaa is the display address in hexadecimal, and bb represents data 
present in memory starting at aaaa. The ASCII characters starting at aaaa are 
given to the right (represented by the sequence of c's), where non-graphic 
characters are printed as a period (.) symbol. Note that both upper and lower 
case alphabetics are displayed, and thus will appear as upper case symbols on 
a console device that supports only upper case. Each display line gives the 
values of 16 bytes of data, except that the first line displayed is truncated 
so that the next line begins at an address which is a multiple of 16. 


-The second form of the D command shown above is similar to the first, 
except that the display address is first set to address s. The third form 
causes the display to continue from address s through address f. In all 
cases, the display address is set to the first address not displayed in this 
command, so that a continuing display can be accomplished by issuing 
Successive D commands with no explicit addresses. 


Excessively long displays can be aborted by pushing the rubout key. 


3. The F (Fill) Command. The F command takes the form 
Fs,f£,c 


where s is the starting address, f is the final address, and c 1s a 
hexadecimal byte constant. The effect is as follows: DDI stores the constant 
c at address s, increments the value of s and tests against f. If s exceeds f 
then the operation terminates, otherwise the operation is repeated. Thus, the 
fill command can be used to set a memory block to a specific constant value. 


4. The G (Go) Command. Program execution is started using the G comand, 
with up to two optional breakpoint addresses. The G command takes one ot the 
forms 

G 
Gs 
Gs,b 


Gs,b,c 
G,b } 
G,b,c 


The first form starts execution of the program under test at the current value 
of the program counter in the current machine state, with no breakpoints set 
(the only way to regain control in DDI is through a RST 7 execution). The 
current program counter can be viewed by typing an X or XP command. The 
second form is similar to the first except that the program counter in the 
current machine state is set to address s before execution begins. The third 
form is the same as the second, except that program execution stops when 
address b iS encountered (b must be in the area of the program under test). 
The instruction at location b is not executed when the breakpoint is 
encountered. The fourth form is identical to the third, except that two 
breakpoints are specified, one at b and the other at c. Encountering either 
breakpoint causes execution to stop, and both breakpoints are subsequently 
cleared. The last two forms take the program counter from the current machine 
State, and set one and two breakpoints, respectively. 


Execution continues from the starting address in real-time to the next 
breakpoint. That is, there is no intervention between the starting address 
and the break address by DDT. Thus, if the program under test does not reach 
a breakpoint, control cannot return to DDI without executing a RST 7 
instruction. Upon encountering a breakpoint, DDT stops execution and types 


*q 


where d is the stop address. The machine state can be examined at this point 
using the X (Examine) command. The operator must specify breakpoints which 
differ from the program counter address at the beginning of the G command. 
Thus, if the current program counter is 1234H, then the commands 


G,1234 
and 
G400,498 


both produce an immediate breakpoint, without executing any instructions 
whatsoever. 


5. The I (Input) Command. The I command allows the operator to insert a 
file name into the default file control block at 5CH (the file control block 
created by CP/M for transient programs is placed at this location; see the 
CP/M Interface Guide). The default FCB can be used by the program under test 
as if it had been passed by the CP/M Console Processor. Note that this file 
name is also used by DDT for reading additional HEX and COM files. The form 
of the I command is 


Ifilename 
or 














Ifilename.filetype 


If the second form is used, and the filetype is either HEX or COM, then 
Subseguent R commands can be used to read the pure binary or hex format 
machine code (see the R command for further details). 


6. The L (List) Command. The L command is used to list assembly language 
mnemonics in a particular program region. The forms are 


L 
Ls 
Ls,f 


The first canmand lists twelve lines of disassembled machine code from the 
current list address. The second form sets the list address to s, and then 
lists twelve lines of code. The last form lists disassembled code from s 
through address f. In all three cases, the list address is set to the next 
unlisted location in preparation for a _ subsequent L_ command. Upon 
encountering an execution breakpoint, the list address is set to the current 
value of the program counter (see the G and T commands). Again, long typeouts 
can be aborted uSing the rubout key during the list process, 


7. The M (Move) Command. The M command allows block movement of program 
Or data areas from one location to another in memory. The form is 


Ms,f£,d 


where s 1S the start address of the move, f is the final address of the move, 
and d is the destination address. Data is first moved from s to d, and both 
addresses are incremented. If s exceeds f then the move operation stops, 
otherwise the move operation is repeated. 


8. The R (Read) Command. The R command is used in conjunction with the I 
command to read COM and HEX files from the diskette into the transient program 
area in preparation for the debug run. The forms are 


R 
Ro 


where b iS an optional bias address which is added to each program or data 
address aS it is loaded. The load operation must not overwrite any of the 
system parameters from @@@H through @FFH (1.e., the first page of memory). If 
b 1S amitted, then b=-@@@0 is assumed. The R command requires a previous I 
command, specifying the name of a HEX or COM file. The load address for each 
record 1S obtained from each individual HEX record, while an assumed load 
address of 1@@H is taken for COM files. Note that any number of R commands 
can be issued following the I command to re-read the program under test, 


assuming the tested program does not destroy the default area at 5CH. 
Further, any file specified with the filetype “COM” is assumed to contain 
machine code in pure binary form (created with the LOAD or SAVE command), and 
all others are assumed to contain machine code in Intel hex format (produced, 
for example, with the ASM command). 


Recall that the command 
DDI filename.filetype 
which initiates the DDI program is equivalent to the commands 


DDI 
-Ifilename.filetype 
-R 


Whenever the R command is issued, DDI responds with either the error indicator 
"2" (file cannot be opened, or a checksum error occurred in a HEX file), or 
with a load message taking the form 


NEXT PC 
nnnn pppp 


where nnnn is the next address following the loaded program, and ppop is the 
assumed program counter (1@@H for COM files, or taken from the last record if 
a HEX file is specified). 


9. The S (Set) Command. The S command allows memory locations to be 
examined and optionally altered. The form of the command is 


Ss 


where S is the hexadecimal starting address for examination and alteration of 
memory. DDI responds with a numeric prompt, giving the memory location, along 
with the data currently held in the memory location. If the operator types a 
Carriage return, then the data is not altered. If a byte value is typed, then 
the value is stored at the prompted address. In either case, DDT continues to 
prompt with successive addresses and values until either a period (.) is typed 
by the operator, or an invalid input value is detected. 


10. The T (Trace) Command, The T command allows selective tracing of 
program execution for 1 to 65535 program steps. The forms are 


vb 
In 


In the first case, the CPU state is displayed, and the next program step is 
executed. The program terminates immediately, with the termination address 








displayed as 
*hhhh 


where hhhh is the next address to execute. The display address (used in the D 
command) is set to the value of H and L, and the list address (used in the L 
command) 1s set to hhhh. The CPU state at program termination can then be 
examined uSing the X command. 


The second form of the T command is similar to the first, except that 
execution is traced for n steps (n is a hexadecimal value) before a program 
breakpoint iS occurs. A breakpoint can be forced in the trace mode by typing 
a rubout character. The CPU state is displayed before each program step is 
taken in trace mode. The format of the display is the same as described in 
the X command. 


Note that program tracing is discontinued at the interface to CP/M, and 
resumes after return from CP/M to the program under test. Thus, CP/M 
functions which access I/O devices, such as the diskette drive, run in 
real-time, avoiding I/O timing problems. Programs running in trace mode 
execute approximately 50@ times slower than real time since DDI gets control 
after each user instruction is executed. Interrupt processing routines can be 
traced, but it must be noted that commands which use the breakpoint facility 
(G, T, and U) accomplish the break using a RST 7 instruction, which means that 
the tested program cannot use this interrupt location. Further, the trace 
mode always runs the tested program with interrupts enabled, which may cause 
problems if asynchronous interrupts are received during tracina. 


Note also that the operator should use the rubout key to get control back 
to DDI during trace, rather than executing a RST 7, in order to ensure that 
the trace for the current instruction is completed before interruption. 


1l. The U (Untrace) Command. The U command is identical to the T command 
except that intermediate program steps are not displayed. The wuntrace mode 
allows from 1 to 65535 (@FFFFH) steps to be executed in monitored mode, and is 


used principally to retain control of an executing program while it reaches. 


steady state conditions. All conditions of the T command apply to the U 
command. 7 


12. The X (Examine) Command. The X command allows selective display and 
alteration of the current CPU state for the program under test. The forms are 


X 
Xr 


where r is one of the 808@ CPU registers 


C Carry Flag (@/1) 
Z Zero Flag (0/1) 


tf 


wo 


Minus Flag (0/1) 
Even Parity Flag (0/1) 
Interdigit Carry (@/1) 
Accumulator (Q-FF) 
BC register pair (@-FFFF) 
DE register pair (@-FFFF) 
HL register pair (Q-FFFF) 
Stack Pointer (Q-FFFF) 
Program Counter (Q-FFFF) 


P~NHMOWPHMmS 


In the first case, the CPU register state is displayed in the format 
C£ZEMfEfI£ A=bb B=dddd D=dddd H=dddd S=dddd P=dddd inst 


where f is a @ or 1 flag value, bb is a byte value, and dddd is a double byte 
quantity corresponding to the register pair. The “inst” field contains the 
disassembled instruction which occurs at the location addressed by the CPU 
states program counter. 


The second form allows display and optional alteration of register values, 
where r is one of the registers given above (C, Z, M, E, I, A, B, D, H, S, or 
P). In each case, the flag or register value is first displayed at the 
console. The DDI program then accepts input from the console. If a carriage 
return is typed, then the flag or register value is not altered. If a value 
in the proper range is typed, then the flag or register value is altered. 
Note that BC, DE, and HL are displayed as register pairs. Thus, the operator 
types the entire register pair when B, C, or the BC pair is altered. 


III. IMPLEMENTATION NOTES. 


The organization of DDI allows certain non-essential portions to be 
overlayed in order to gain a larger transient program area for debugging large 
programs. The DDI program consists of two parts: the DDI nucleus and the 
assembler/disassembler module. The DDI nucleus is loaded over the Console 
Command Processor, and, although loaded with the DDT nucleus,’ the 
assembler/disassembler is overlayable unless used to assemble or disassemble. 


In particular, the BDOS address at location 6H (address field of the JMP 
instruction at location 5H) is modified by DDT to address the base location of 
the DDI nucleus which, in turn, contains a JMP instruction to the BDOS. Thus, 
programs which use this address field to size memory see the logical end of 
memory at the base of the DDI nucleus rather than the base of the BDOS. 


The assembler/disassembler module resides directly below the DDT nucleus 
in the transient program area. If the A, L, T, or X commands are used during 
the debugging process then the DDI program again alters the address field at 
6H to include this module, thus further reducing the logical end of memory. 
If a program loads beyond the beginning of the assembler/disassembler module, 
the A and L commands are lost (their use produces a "?" in response), and the 





trace and display (T and X) commands list the "inst" field of the display in 
hexadecimal, rather than as a decoded instruction. 


IV. AN EXAMPLE. 


The following example shows an edit, assemble, and debug for a simple 
program which reads a set of data values and determines the largest value in 
the set. The largest value is taken from the vector, and stored into "LARG 
at the termination of the program 


ED SCAN.ASH 
| a aia, 

















eS vs jr, pout echo 
> tr orc tr" 106  =LALSSTART OF TRANSIENT AREA, 
M¥I B»LEH iLENGTH OF VECTOR TO SCAN, 
Wy c.a /LARGER-RST VALUE $0 FAR, 
LDOP Ss P20 02k) id Hi VECT BASE OF VECTOR, 
Loor:* Moy at ;GET VALUE, 
SUB ie ;LARGER VALUE IN C? 
ajo oINE NFOUND iJUMP IF LARGER VALUE NOT FOUND 
5 wer NEW LARGEST VALUE, STORE IT TO C, ‘ 
nov ca 
NFOUND: INX H ;TO NEXT ELEMENT 
DCR B :MORE TO SCAN? : Create Source 
| JNZ OOP iFOR ANGTHER, Progvam. - underlined 
4 
se END GF SCAN. STORE C, Chataders typed 
Moy fet sGET LARGEST VALUE 
Sta LARGE, 2» oy Pago mes, 
JHE fo. jREBOOT , of ve neseuks CofMiage 
a TEST DATA resurw. 
VECT: DB 2,0,4,3,5, 6.155, 
LEN EGU F=VECT sLENGTH, 
LARGE: DBD i ;LARGEST VALUE ON EXIT 
END "ts - 
te saree” 
«BaP 
7 ore 19@H =iSTART OF TRANSIENT AREA 
Mv I B»LEN iLENGTH OF ¥ECTOR TO SCAN 
M¥I C.6 ;LARGEST VALUE SO FAR 
LXI H»VECT ;BASE OF VECTOR 
LOOP. Moy AM iGET VALUE 
SUB C ;LARGER VALUE IN C? 
UNC NFOUND ;JUMP IF LARGER YALUE NOT FOUND 
NEW LARGEST YALUE, STORE IT TO C 
Moy CA 
NFOUND: INK 4 ;TO NEXT ELEMENT 
DCR B ;MORE TO SCAN? 
JNZ LOOP ;FOR ANOTHER 


10 


c™ 


STORE C 


iGET LARGEST 


j;REBOOT 


2.4.4.3,5,6.1,5 


END OF SCAHH. 
MOY A.C 
STA LARGE 
ul PP Ss) 
; TEST DATA 
VES IB 
LEN E Qiu $-VECT 
LARGE US i 
EN ft . 
rE 4— End of Edit 
ASM SCAN 


CP/7M ASSEMBLER 


Hi2e 
GGZH USE FACTOR 
ENT GF ASSEMBLY 


TYFE SCAN. FRN 


2 Start Ascewller 


WER F.% 


iLENGTH 
sLARGEST 


VALUE 


VALUE 


GOH E#TT 


Assembly Comolede - lock at Fropram Lehi 


Code Mawes. 


v 
S 
Machine Code ( 


wie Hegvam 


SCAN 


NOT FOUND 


t 


B1iGG ORG 1@GH i START OF TRANSIENT AREA 
@100 a6a3 MY I B, LEN iLENGTH OF VECTOR TO 
G142 GEBe My I C.G jLARGEST VALUE SO FAR 
@1@4 2119681 LI H.VECT GBASE OF VECTOR 
@1a7 7E LOOF: Moy 4. GET VALUE 
@ias 91 SUB C jLARGER VALUE IN C7 
8169 D2aD81 JNC NFOUNG i JUMP IF LARGER VALUE 

NEW LARGEST YALUE. STORE IT Ta € 
@1aC 4F MOY C: A 
@14D 23 NFOUND:. INX H iTO NEXT ELEMENT 
BI1HE @5 BCR P iMORE TO SCAN? 
B1GF C2a761 JNZ LOOP iFOR ANOTHER 
END GF SCAN, STORE C 

@112 79 Moy H.C iGET LARGEST VALUE 
@113 322161 STA LARGE 
@116 bade JM 8 REROUT 

Code /e isting ; 

“Truncated TEST DATA 
B119 G@20G04G3G5¥VECT. DE 2 i Be he oS 
agag = ¢ LEN Eau $-YVECT iLENGTH 
#121 Valuect LARGE: DS 1 ;LARGEST VALUE GN EX 
@122  Equale END 
A> 


\\ 











UIT SCAN. HEX 


1oKk 
NEXT 


Mi2i, 468 


DUT 


PC 


VER 


ees ee eee 
~? 


ft Ss 


é 


-K 
—? 


aise 
Bie 
H1M4 
816" 
W1ias 
B1iuy 
H1GC 


B1iGD 


G1ae 
hi Ge 
Biie 
=i 

=% 
Bids 
Hiie 
#119 
BiLlA 
MiiB 
B1LiC 
110 
Ci Le 
H1i26 
Miz} 
a124 


“Allis 


Wile 


ea 


Wiis 
BitLé 


Lxi 


RST 


STA 
RST 


ever 


rmemrano er ror om 
a Si il ry oa %e omy 
ma & 
m= 


x 
om 


B 
B 
B 
&.@1 
B 
it 
H 


O26 


iuline assem 


a ee 


2 Start Delugrer usu hex Sywat machine Code 
1a 


Last lood addyess + 
COZGMGEGIG A=00 B=000G D=8ea8 H=G008 8 
A cramue veqstors loefoe debug run. 
reeeee Change P40 (00 

love at vesistrs again 


COZOMHEGIl& A=6G B=h4ae 
-L1@@ 


aD 


neck wetuctian 





S=@100 Faia NY¥I e438" ) 
Neck ruchvuction 
ty Aecute at Pe=Wo 


0 saccembled Mach ne 


(ode at (00H 
See Sauce Licking 


(wate hal Program 
ends at location IIb 
J wrth a Tu? 4p 0000) 
ly mode to clonse 
will Cause the Program und 
7 1S vey executed, 
B117, (angle carriage Veluin stoRS assem 


Lt cede at SH to check Huh 2517 Wns Proper 
12 Place 
ta 


cud 
Sie UP + 000) Ito a RST 7, Which 
or ~est to velum to ODT Ff WH 


—_ = OO ___...__— ee 


@ii? NOP 

Biis& HOF 

Hii19 STAxK & 

wbitsé NOP 

WIL INF B 

Bite INS sd 

“Ks losk al veaistis 


COZG@MBEGIG A=@0 B=G@086 D=86G6 H=H000 S= 


Execute Progvam-or one Step. 


ie! 
~~ 





COZ7G@MH@EG1@ A=GG B=0G00 N=808G H=@808 S=G@10G P=@1GG M¥Il B.&S*eO182 
~T : 

—~? Trae one ep aaa (vate OSU in g) audowatté veal pot 2 
C@ZG@MG@EQ@1@ A=0G B=GS6H D=8G08 H=0G08 S=G108 PHeGiG2 M¥Il C,.@G*6184 
-~T7T on e 3 e 

? Trace agam (Rajiskr C cleared) 
COZUMGE@IG A=GG B=8SH0 D=G00G H=GG08 S=G10G PH@1G4d LXI H.@119"0187 

T3 

= Trace three steps 
COZGMBEGIG A=G4@ B=0806 D=800H H=@119 S=@10G PeG@ia7 Moy A.M 
COZOMG@E@IG A=02 B=8800 D=868H H=G119 S=@910G P=@108 SUB C 
ee. A=62 B=@908 D=8G00 H=G119 S=G10@ Pe@lad JING G1aD*e14ED 
-[1 . 

a) Oistloy Wem davting at (14H, em Gidomade breakpowtt atop 
H1i19/82 Ga 64 o3 O5 BE BD Magramao 7a 
Bi2@\e5/11 @@ 22 21 8@ &2 VE EB 77 13 23 EB OB B 4 hw 
G@iz@ C2 27 61 C3 3 29 BO 6 B88 GB 4G AG aa oa GB ae .’...>. 
H1i4@ 66 86 GG 88 BH BO 2H 4G BB BA 4G BA a Be Be Be 
A150 O@ G@ GO GH GH BE BG OG BA GH Ge Ga ae Ga oe aa Dt i dite 
G160 GG GG 0G 98 G2 BG GO 40 48 46 HO AG OO GH OH Be YY. heer tenth ate” 
h1i7G 86 G@ 86 BB GB BH GA GH BB OH BG HA Be aH aa ua Li fa 
Hic G6 O@ BH GA G6 6 6 OH GH AG AH 4H 4H Ga Ba ae wate Q05¢ ono 
W190 G@@ GG GG BH BO BG 2G BA BB AG OG GO 24 OH Be ae WON. ee Ce 
H1AG@ G6 G4 24 66 BH BO OG BH BB Gh AG BA a4 Ga oe ae chovacters . 

H1BG@ 8G GA 66 BB BH BR OH 42H OB GH BO BH Ga BA oe ae 

Hich B8@ G6 94 86 G6 @G 46 BG OB AaB AG HO Ba Ge ae ag 

“2 Current CPu state 

COZGMGEQ@I11 A=02 B=8S0G D=8000 H=@119 S=G@i@H Fea@iap INK H 
-T5 

me Trace $ <kes fiom Curveut CPU Stade, 

COZ@MBE@11 A=02 B=@80G D=0G00 H=@119 S=@100 P=eH1eD INK H 
CGZUMBEG@I1 A=02 B=8800 D=8G@0R H=4116 S=G18G FeGiGE TCR 8B Automoce 
CAZ@MBEG@I1 A=02 B=0700 D=G@00G H=G11A S=G1G@ F=A1GF UNZ 8187 Breakpout 
COZGMBEGII pte R=@70G U=G@0G H=G@1108 S=@18@ P=8147 MOY 4.M 
C@Z@MBEG]11 A=GG S=0700 D=8G00 H=G11q S=Giaw Pefias SUB C#H1Aa9 
eee 

¥ Wace silat listing ucterwed lade. states 
COZIMGELIL S=86 B=8700 D=BG08 H=11h S=@1e@G@ P=@1G9 JUNC @1e@D*ai484e 
_s, COL Stote at tud of US ) 
COZ@MBEL1I1 A=04 B=8600 D=@800 H=@118 S=f10@ Praiae SUR Cc 






W1@@ P=8145 


MMVI 


B. 83 


muttal CPL Stee, before ) is aecukd 











SAVE 1 SCAN. COM 


“Sy Pun Program tem cunext PC until ComPletion Lia real-ture) 
vig \reakeowt ot UGH) caused by eecutng RST 7 in Ynaclune Code 
“*y Coucade at ond df Prog wan 


COZIMBELI1 R=46 B=8G606 T=G080 H=G121 S291 P=9116 RST a7 
“BED ¢vamme and change Pwaiam Counter 


P=G116 169 
4 

x 

“9 









COZIMGELITL A=G6 B=0008 D=8e6e H=G121 S=aiwe Fs saat My ht 


“Les “Tyee {0 lakeua 1) eps fret do clone yeork oes? 


Em 
S 









Cw 
COZIMBELIL A=BH B=G@686 D=8o0o H=61271 Ssfiua P= et iar B,88 
COZIMBE1I1 A=88 H=G124-S=@1@@ Pe@ig2z MYI o. 466 
C@ZIMBEL1I1 A=G4a Hei2i S=@1aG P9104 LXI H.@1193 
CQZIMBELI1 A=a8 LET H=G@119 S=Gia@ Peaiag?7 MOY A 
COZIMBEIT1 AACE ae H=G119 S=@1ia@G@ PsRia@s Sue ¢ 
COZ@MBEQGI1 A=@2 B=880G D=G6080 H=@119 S=G18G P=@199 UNE 
COZGMBE@I1 A=@2 B=8G00 N=80@4G H=G119 S=G10@ P=@10D INS 
COZ@MBEG@I1 A=@2 B=@98G D=8G04 H=G11A8 S=@1GG P=@1GE ICR 
COZGMGE@I1 A=G2 B=870G D=@00 H=G11A S=@14G P=@1GF JNZ 
COZOMBEGI1 A=@2 B=G786G D=8000 H=G11A $=010@ Pe@1e7 MO 
COZ@MBEQ@I11 A=G@G B=@700G D=@G08 H=G@118 S=G10G P=Mlas SUE 
COZIMBE111 A=@6 B=A700 D=@600 H=@11A S=@14G FH@1H9 INE 
COZIMBE111 A=@@ B=G70G D=8G00 H=@118 S=@10G Pe@i@D INX 
COZIMGE1I1 A=@@ B=G700 D=8000 H=G118 S=@18G F=@1GE DCR 
COZQ@MBE111 A=@@ B=G606 D=FG00 H=@11B &=@1G@ P=@1G@F UNZ 
COZ@MGELI1 A=@@ B=860G D=8GG9 H=@118 S=8@1G8 P=G1G7 MOY a, M*a1as 
-A1a3 oO . 
@  Dusert a bat porte” inte Plavamshould Mave wuved the 
fiag Jc ian Wwe wachine Code ae | 
a aman Value wom A wo C since AC. 
Ai ac +o Chana the 
Hi a Smee +k Leh 
2 Tx + Ie. me this Code was not executth, 
ai it Gppeave that tHe Th 
at ‘Sve WT Sotut & version of i? “the INC shsulA 


“the Patched Program can be Saved Wave been a TC swestructum 


2 Poavam vesides on inst Fige, so Sav 1 Pose . 
POET EON COM — Restart DOT uct the Saved memwy mae to continue tein 


isk DDT VER i. @ 
NEXT FC 
Hcaa 14a 


pL List some Code | 


Big@® M¥I §&.68 

W192 M¥I C.@6 

B14 ap Ae ara eae Patch ic Preseut wv in X-COM 
Hike FOV 4g. ff 

Hig& SUB ¢ 

H1ia9 JC 1G 











Date is mored from A- C 


B19C MGY C4 
2190 INK 4H 
S19—E DCR #z 
@1@F JNZ 8187 
B1i12 MOY «a4. 
-~xfP 

=— 
F=6166 ) 
rae, r lace ty Se how Pictched veysun operates 
COZO6MBEG1G S=66 B=8066 D=0G00 H=: 5 e1eaB 
COZOMBEGIG A=66 B=68606 D=8098% H=4 Ss ALaz 
COZOMBEG1G H=06 B=a806 I H=g Ss A1a4 
COZGMGEGI1G A=06 B=0808 DBD H=@ C=K =A107 
COZGMBEGIG A B=a80e D H=g S=@ P=@149 
COZOMBEGI1 A=82 BS B S=@ P=8109 
COZG@MBEG@11 A=62 8=8% I= S=@ P=@1@c 
COZQMBE@11 A=02 B=8 D=@908 H=G119 S=@108 P=a1eED 
COZGMBEG11 A=62 B=6882 D=860G H=G119 S=G14@ P=G1GE 
COZ@MBEG11 A=62 B=8782 D=8G0G H=G11h $=@186 P=@16F 
COZOMBEQ@11 A=42 B=8702 D=80GG H=G119 $=0188 F=814? 
COZG@MGE@11 A=00 B=G702 D=AG0G H=G118 S=010G P=0168 
C1iZ@M1iE@I1@ A=FE 8=8782 D=8@908 H=G110 S=010@ P=8109 
CIZGMiE@I1G A=FE 8=8702 D=6000 H=911Aa $=4180 P=alaD 
CIZQM1EG@16 A=FE 8=0782 D=8009 H=G116 $=@14@ P=@10E 
CLZGQMBEL11L A=FE B=8682 D=@@00 H=@118 $=818 P=G10F 
-& « 
-y leak Po urt 
CLZQ@MBE111 A=FE 8=@642 D=8066 H=a118 $=@18@ P=8167 
“G2188 | Runtiom Curent PC and breakpoint at 10H 
*B1iGBSs 


CIZG@MBELI1 A=64 B=@662 D=8608 H=8115 F-61468 


~T ° 

“2 Siugle Step tor & Feus cycles 
CIZOMBE1I1 A=84 B=G602 D=8008 H=01168 S=a14a¢ 
“A 

+ 

COZ@MGE@11 A=a2 B=a6e2 
“AY 


C@Z@MBEGI1 A=H2 B=45be FI 


oa Run +o ComPlehon 


=HU¥G86 H=H118 S5=4146 


COZIM@E1I1 A=83 B=8063 D=9G08 H=6121 
a look ak the value cf Lage” 


8121 83, Wrong Value! 


=01uG 
-S$i2il 


P=#a1@e 


P=#116 


Mid] 8,44S 
MV] =. 48 
2 | H,@113 
MOY Q.f 
SUB § 

JC 8163 
MOY c.f 
IN® rf 

BOR B 

JINZ 2167 
May Q.f 
SUB C 

JC 81aD 
IN& H 

DCR 3) 

JNZ @1807*89187 
afer \b skps— 
MOV ALM 
SUB oC 

SUE Ceaies 
JIC ViebDeaiac 
MOY oe A 
RST a7 














a A Nar 


Migr Ee 
—) 
-Lia 
= 
Hie M¥I 
Hise MI 
Rigd  LxXI 
His MOY 
HiWMe SUE 
Hiag JC 
@iaC Moy 
M1 oi IN¢ 
HigeE DCkR 
M1 aF JNZ 
Hite May 
= 
—y 


@11&8 NOP 
Bil9 STRY 
BitA NOP 
BH1iLEe INR 
BiiC INA 
Giit UCk 
Wile M¥I 
Mica OCR 
aE 

—~? 


P=G116 160 


3 Swale 


LOzingest4 
~? 
COZIMGELT! 





mmo mo ow 


: Reset the Pe 
Se, and watch data values 


A=@3 B=@003 D=8@86 H=@i2e1 S=G1@@ FGioe MY¥I 


A=G3 B=G803 D=Q000 H=G121 $=@14G P=B142 MY¥I 
Court sel 
F  — larqot'set 


A=G3 B=490@ L=@64660 H=G121 S=@106 


B.@3*@102 


-,BO*O104 


»-B1139%6167 


3. h461 88 





—,/ 
COZIMBELI 1 
“LT 
COZa@MHnEel i 
-~T 

a 
CHeZaAMBEGI i 
-T 
—2 
CUZe@nG@Eeli 
ou 

| 
CeZeMBeai i 

-T 

Vv 
CeOZEGNBEG@I IL 
-7 

ae 
CaZGMBEGT 1 
-T 

3 
COZaMBE@I 1 
~T 

~~ 
CLiZeaMiEala 
-T 

“~ 
CiZaMiE@la 
-~-Li@a@ 

Aiwa MY¥I 
Hiae M¥I 
Aig@d4 LX] 
Bia? may 
H1i9e& SUB 
#189 JC 
Hiatt Moy 
B19 INX 
HiSE DCR 
BiBF UIN2Z 
BilzZz May 
-AL1aS 
Wigs CRF 
Hiwg f 





ctust date, a broug ict +) A 


A=@2 B=8500 D=@aGm H=6119 SUE 


Peas JC 


MOY 


R=2 Brey ae h=eR ee H=811S 5=8i¥86& 
(o Steond dota tte lovouglet tp A 
B=8702 D=G@@00 H=@118 S=G1@ P=H10a8 SUB 


Subtract dectvoys dada Value whacl, Was loaded I f 


B=@76e D=@6@@ H=@11A S=@G@1eG@ P=@149 JC 


R=86 


A=FE 


P=a@ielh IN% 


@1@0 
C.A 
H 


would vst le deetroged. 
: 

@187 

aac 


lat Patch at (08H clanyes Sus to CMP 
ie 


C#eleasg 


BLiade@iac 


C.A*81 aD 


H*Q@Q1BE 


B*eO@igr 


BiB7+*B147 


A. M*eai ee 


C*@iag 


Bi1aD*a148D 


H#@ LE 


i neta chould lave been a CMP so-that veqrstr A 





SAVE 1 SCAN. COM : 
<P Save memory mage 
AeDET SCAN. C 

SCAN ee Cast art DOT 

iek THT Ver t.@ 
NEXT PC 
B2a6 8166 
~AP 

—¥ 
Pal aay 


Hii6 RST @7 

Ait? NOP ¥ . 

Bile NOP 

oe te L at code to see if tt (UGS Properly Loaded 
Bi1Aa NOP (long type out aborted wt Yuloorct) 

~ Cruloout) 


ge Cun tvom Oa +o completuon 
16 
—~) Look at Carry (oadewtal type) 
C1, 

“Ay Look at Cru strte. 


CiZiM@Ell1 A=@6 B=f486 [T=8h59o H=G@1271 S=418 
et 


mS 
“tl 
t 
css 
fue 
oeechs 
Ty 
43 
fame 
=f 
ys 
~J 


7 
ZT 


=> ook at Lave” - (+ appears 4p he Correct 


wlzl @6 


;LARGER VALIIE IN ft 





jLARGER VALUE IN 6? 
INE NFOUNE ;JUMP IF LARGER VALUE NOT FOUND 
snc Delt Jat T 
aC NFOUND oj JUMP ITF LARGER VALUE NOT FOUND 
“kn 


Ie 


nS SCAN Aez > Qo geceuible, <electing source rom dick A 

CPeH ASSEMBLER - YER 1.8 Wx to disk A t fle) 
Pout to E (selects wo Prat le 

Bigs 

Veen Ben Feuer 

END GF ASSEMBLY 


OT SCAN. ne Veevau deluager dy check Chavats 


tek DDT VER 1.4 
| NEST PC 
| AiZ1 @aoe 
| ee 
| : . 
site ume aooa Check yo ensue endis till at (LY 
W119 STAX B 
| Hite NOP 
| file INR & 
| ~ (ruloout) 


| “Gite, Pie , (0 trom bea wring wth leak Pot ak end 
, GLLE lovcak Pott reached 
am EEL, Look at Lace! Corvect Value ComPucted 






| hier oa 22 21 GO OS 7E ER 77-17 PEER OR 78 Bi 2. MELLEL 
| hitG C2 27 1 CR @® 29 GA OH BA BA GG 4 OG BA SH 4H .°..0d.. 
Ni40 84 @@ 426 BA GO G6 8G 2&4 4 GA BH 4H GH BH oe fe 


- (vulesut) alow's lon tupegut 
=) <S1op DOT, debua SSSt6n Complete 


a er a a ce ce 


























DIAGNOSTICS 


Your 820 comes with a Diagnostic Exerciser disk. You can use this disk to check that 
your 820 is in proper working order. The disk will check the different components of 
the system and display a message if it finds a malfunction. 


It's a good idea to check your system when you first install it. If you experience any 
problems while using the system, you can use the Diagnostic Exerciser to check the 
system and find out if it needs to be serviced (repaired). 


HOW TO BEGIN: 


OPEN the disk drives (shown below) and remove any disks 


5%" DISK DRIVES 8" DISK DRIVES 
DRIVE DRIVE DRIVE DRIVE 


ss Fone ey 





= 


NT | 
fl | 
| 


| 
wll 


LOCATE the ON/OFF switch on the left side of the 8" disk drives (shown below) 
(The 5%" disk drives does not have a ON/OFF switch) 


LOCATE the ON/OFF switch under the right side of the screen (shown below) 


SCREEN 8" DISK DRIVES 


RESET 
BUTTON 
(on back of screen) 
BRIGHTNESS 
CONTR 
(under edge of screen) 
ON/OFF 


SWITCH 
(under edge of screen) 





ON/OFF 
SWITCH 


DIAGNOSTICS 


9. 
7/1/81 


TURN the screen on -- if it is already turned on, press the RESET button at the 
back of the screen 


TURN the 8" disk drives on -- if your system has 8" drives, they must be turned 
on for your system to operate. 


WAIT for the word XEROX to appear on the screen. If it does not appear after 
a few seconds, try adjusting the brightness control (under the left edge of 
screen) 


If nothing appears on the screen, your system needs servicing 


When you use the Diagnostic disk to check out your system, you'll need to have an 
initialized disk to put in the other disk drive. (An initialized disk is a disk that has 


been prepared for Use in the 820.) If you just installed your 820, you'll need to use the 
instructions below to initialize a disk. 


TO INITIALIZE A DISK: 


INSERT the CP/M disk in the left drive (Drive A) and close the drive 


D5%" DISK DRIVES 8" DISK DRIVES 





INSERT DISK 
DRIVE DRIVE 
A B 








CLOSE DRIVE 


DIAGNOSTICS 
7/1/81 9-2 


— 





TYPE A and press RETURN 


OBTAIN at least one new disk and take the write protect tape off of the 5%" 
disk, or put a write protect tape on the 8" disk. 
(If you don't have a new disk, a previousley used one will do.) 


5%" DISK 8"DISK 
UP AND IN 
WRITE ARROWS 
PROTECT 
TAPE 
WRITE 
PROTECT 
OVAL TAPE 
CUTOUT 





TYPE the word INIT and press RETURN 

WAIT for the message "ENTER DISK DRIVE TO BE INITIALIZED (A or B)" 
INSERT the new disk in drive B 

TYPE B and press RETURN twice 


WAIT for the message "0 FLAWED SECTORS" to display 
If the disk has flawed sectors indicated by a number other than 0 in front 
of the FLAWED SECTORS message, do not use it - initialize another disk 
using the steps below. 
@ Replace the disk in drive B with another disk 
@ Type B and press RETURN twice 


e Wait for the O FLAWED SECTORS message to appear 


REMOVE both disks 


You're now ready to check out the system with the Diagnostic Exerciser disk. 
The instructions for running diagnostics are on the next page. 
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TO RUN DIAGNOSTICS: 


Before you run diagnostics, you'll need to put paper in your printer (use two sheets, so 
that the paper covers the width of the platen), and turn on the printer. The On/Off 
Switch is on the back of the Diablo 630 printer. 

As the test runs, you'll need to watch the screen for error messages. 


PRESS the RESET button on the back on the screen (shown on page 9-1) 


CHECK the Diagnostic disk to be sure that it is not write protected. 
(The 5%" disks are not protected when the tapes are removed, and the 8" 
disks are not protected when the tapes are on.) 


INSERT the Diagnostic disk in the left disk drive (Drive A) and close the drive 


INSERT an initialized disk in the right disk drive (Drive B) and close the drive 
(Be sure that the disk is not write protected) 


PRESS the A key and the RETURN key 


The diagnostic disk will begin to check out the system. Be careful not to 
touch any keys on the keyboard while the test is running. Touching a key 
can stop the test. 


Note: If there is an error during the test, pressing CTRL + C will run the 
remaining tests 


WATCH the screen for the results of the first memory test. In about 30 
seconds, the screen should show: 


PASSES COMPLETE = 0001 ; COUNT OF ERROR BYTES = 0000 
PASSES COMPLETE = 0001 ; COUNT OF ERROR BYTES = 0000 


If the COUNT OF ERROR BYTES does not equal 0000, your system 
needs to be serviced. 


WATCH the screen for the results of the second memory test. The screen 
should show: 


PASSES COMPLETE = 0001 ; COUNT OF ERROR BYTES = 0000 
PASSES COMPLETE = 0001 ; COUNT OF ERROR BYTES = 0000 


7/1/81 gis h a 


If the COUNT OF ERROR BYTES does not equal 0000, your system 
needs to be serviced. 


WATCH your screen for the results of the disk test. The disk drives will click 
during this test. When finished the screen should show: 


0 read/write error detected 
0 seek errors detected 


WATCH the screen test as it displays the screen test. The test pattern should 
fill the screen with characters. (The boader around the test pattern will 
remain black.) 


If there are missing characters or irregularities in the test pattern, your 
system needs to be serviced. 


(If you do not have a printer, the test will end here. Remove both disks 
and press the RESET button.) 


WAIT while the printer prints its test pattern. (If you have an 88 or 
92 character wheel on the 630 Printer, the test patterm will have blanks 
in some places.) 


If the test pattern did not print the alphabet and numbers, or if the 
characters were not properly aligned on the paper, your system may 
need to be serviced. 


LOOK for the message "DIAGNOSTIC COMPLETE. RESET TO CONTINUE" 


REMOVE the Diagnostic disk and the initialized disk, and place them back in 
their disk envelopes. Your manual has a disk holder at the back that you 
can use for storing your Diagnostic Exerciser disk. 


PRESS the RESET button. 
If all the test messages corresponded with those shown in the instructions, your 820 is 


hooked up correctly and in proper working order. 
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DIABLO 630 PRINTER 


INTRODUCTION 

Diablo Systems has combined the simplicity and reliability of a newly designed daisy 
wheel printer with the latest microelectronic technology to produce the Model 630 
Printer. 


The Model 630 is a universal RS 232-C interface printer. It will support a heavy 
work load using conventional serial data interchange techniques and protocols. 


The Model 630 can use all Diablo and Xerox plastic and metal print wheels. 


The Model 630 can use many of Diablo's present paper handling devices, such as 
forms tractors, sheet feeders, etc. 
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UNPACKING THE 630 


l. 


Take the printer and all accessories out of the carton and remove the plastic 
dust bag. Place the Model 630 on a desk or table. 


NOTE: The weight of the Model 630 is centered toward its right rear (as you 
look at it); thus it is easiest to lift by holding it at the right-rear and left-front. 


Inspect the Model 630 and any accompanying accessories for evidence of | 


shipping damage. Immediately notify the shipping agent of any damage to the 
unit or its parts. 


Remove the access cover. It is held in place by magnetic latches in front and 
small tabs in back. 


Remove the plastic bag and the CAUTION tag attached to the paper bail by 
cutting or removing the tie wrap (nylon strap). 


Remove or cut the following shipping restraint items if installed (see pictures 
on opposite page): 


a) Rubber band securing the cover open switch actuator. 


b) | Rubber band securing the paper cradle to the paper pressure rollers (if no 
platen is installed). 


c) Tie wrap (nylon strap) holding the carriage to the right printer frame. 


CAUTION: DO NOT cut any other tie wraps! 
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REMOVE RUBBER BAND 


ACCESS COVER 


CUT TIE WRAP 


REMOVING SHIPPING RESTRAINTS 
SYSTEM COMPONENTS 
1 








1. 


INSTALLATION 


Place the Model 630 on your desk or table. Look at the two cords. One printer 
cord plug fits the large outlet on the back of the printer; the other plug fits the 
large outlet on the back of the 820's screen. One power plug fits the smaller 
outlet on the back of the printer; the other plug fits a wall outlet. 


Check the ON/OFF switch on the back of the printer -- it must be OFF! 


Plug the printer cord into the large outlet (right side, looking at back -- see 
picture on the opposite page) on the back of the printer. Tighten the screws on 
the plug. 


Plug the L-shaped end of the power cord into the small outlet (left side, looking 
at back -- see picture on the opposite page) on the back of the printer. 


Plug the other end of the power cord into the wall outlet. DO NOT turn on the 
printer yet. 


If the platen has been removed, reinstall it by lowering it down into place while 
pressing down on both platen release levers. 


NOTE: Make sure the platen's releasable drive gear end is on the right (as you 
view it). 


Install the platen knob on the right end of the platen - thru the hole in the top 
cover. Engage the knob on the platen shaft, rotate the knob until its slot fits 
over the cross pin on the platen shaft, then push against the knob to snap it into 
place. 


Install a print wheel and ribbon (see instructions on Pages 10-8 and 10-9). 


Install the access cover. It is held in place by magnetic latches in front and 
small tabs in back. 


Install the sound cover. Insert the sound cover pivot shaft in the tabs located on 
the top of the accesss cover. 
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FAMILIARIZATION 


(See picture on opposite page) 


l. 
2. 


Control Panel - Operator control switches and indicators. 


Access Cover - Operator access to internal controls and for changing print 
wheels and ribbons. 


Platen - similar to those on standard office typewriters. There is a hand knob 
on the right side only. 





Paper Handling Features 


4, 


Platen Knob - This knob, when pushed in (to disengage the drive gear), allows 
the operator to rotate the platen to insert and position paper. 


Platen Release Latches - These two latches are pressed down simultaneously to 
insert a platen or to release the platen for removal. 


Paper Bail - The paper bail holds the paper against the platen for optimum print 
quality and quietness. The bail must be pulled forward (away from the platen) 
when inserting paper. 


Paper Release Lever - This lever releases paper roller pressure when pulled 
forward, allowing the paper to be positioned manually. Returning this lever to 
its back position reestablishes paper roller pressure. 


Paper Guide - A movable guide for aid in inserting paper. 

Paper Scales - There are two scales associated with the Model 630. One is a 
column indicator, located on the top cover; the second is a paper scale mounted 
on the access cover. These scales aid the operator in centering and spacing 
paper and copy. 


Power Indicator Light - This light indicates that the power is on. 
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PREPARATION FOR OPERATION 


Installing a Print Wheel 


CAUTION: Ensure that power to the Model 630 is turned OFF! 


1. Grasp the print hammer assembly and pull it toward you to tilt the print wheel 
mechanism away from the platen and card guide. 

2. Rotate the print wheel motor hub to bring the hub's alignment tab to the upper 
part of its arc of travel. 

3. | Grasp the print wheel (metal or plastic) by its rubber hub and place it on the 
print wheel motor hub. Align the wheel's alignment slot with the hub's 
alignment tab, and push the wheel firmly to fully seat it on the motor hub. 

4, 


Tilt the print wheel mechanism back to its operating position. 


Removal of the print wheel is simple. Tilt the print wheel mechanism toward you, 
grasp the print wheel by its rubber hub and pull it free of the print wheel hub. 


Note: Diablo print wheels are rugged and dependable, but they can be damaged. 
Use care when handling them to avoid bending the "spokes". Always store 
print wheels in their plastic containers when they are not installed in the 
printer. 


PRINT WHEEL 
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INSTALLING PRINT WHEEL 
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Installing a Ribbon Cartridge 


Open the plastic envelope and take out the ribbon cartridge. Note the small 
knob on the top surface of the cartridge for advancing the ribbon manually. 
Use this knob to take up any slack in the exposed portion of the ribbon and to 
make sure the ribbon is tight and straight. 


Hold the cartridge in one hand with the exposed ribbon toward the platen. 
Lower the cartridge down over the print hammer guide (orange stripe). Be sure 
the exposed ribbon is straight and located between the card guide and print 
wheel. Push the cartridge down firmly until both latches have snapped into 
position. Rock the cartridge back and forth on the platform to ensure that the 
ribbon is free to move up and down. Turn the ribbon advance knob a turn or 
two to ensure that the ribbon is tight, straight and ready to operate. 


The ribbon cartridge may be removed by pressing down on both latches 
simultaneously. The cartridge will be raised up slightly and may be grasped 
easily and lifted out of the printer. 


Note: When a ribbon cartridge is nearly empty, a yellow cross-hatched pattern 
will appear on the visible back side of the ribbon. The Model 630 will stop 
printing, sound its alarm and the RIBBON/PAPER light will come on if printing 
is attempted with the ribbon in the warning (yellow) zone. 


PRINT HAMMER 


RIBBON GUIDES 





RIBBON CARTRIDGE 


LATCH 


IMPRESSION CONTROL 


INSTALLING A RIBBON 


SYSTEM COMPONENTS 
10-9 


Inserting Paper or Forms 


Inserting paper or forms into the Model 630 is accomplished in much the same manner 
as in a standard typewriter. Paper is inserted down behind the metal paper out bail 
and platen while the platen is turned manually to bring the paper around and up in 
front of the platen. The front paper bail (Item 5, page 10-6) aids in guiding the paper 
back over the platen to the rear when pulled forward. The paper release lever at the 
right-hand side of the printer may be pulled forward to release roller pressure after 
paper insertion so the paper can be properly aligned in the printer. After paper is 
positioned, both the front paper bail and paper release lever are returned to their 
operating positions. 


Paper Thickness/Print Intensity Adjustment 


The two-position Multicopy lever located at the front of the carriage assembly 
adjusts for paper thickness and print intensity. Setting the lever to its upper position 
moves the carriage close to the platen, and actuates a switch to the proper setting 
for light and medium weight paper and form sets of up to two carbon copies. For 
heavier paper or form sets of up to five copies, the Multicopy lever is set to its lower 
position. This rocks the carriage away from the platen slightly, and deactivates the 
switch to enable an increased print intensity. 


To avoid the possibility of ribbon damage, the Multipcopy lever should always be set : 
at its upper position when printing on single sheets of paper using carbon ribbons. 
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OPERATING THE MODEL 630 PRINTER 


Preliminary Steps 


Install a print wheel, a ribbon cartridge and insert a sheet of paper - as outlined 
on pages 10-8, 10-9 and 10-10. 


Move the carriage manually to the right a short distance. 
Move the power ON/OFF switch at the right rear of the printer to ON. 


The POWER indicator should glow; the carriage should move to the left slowly, 
and then back to the right, to stop at the first print position; and the print 
wheel should rotate and stop at its "home" position (i.e., the "flag" on metal 
print wheels should be at the top if the Print Wheel Select switch - under the 
access cover - has been properly set). This entire process is called the 
INITIALIZATION, RESET or RESTORE sequence. It clears all volatile memory, 
resets all position counters and sets the Model 630 to print the first character. 


Paper Handling Accessories 


-Forms Tractor/Pin Feed Platen: These devices facilitate precision handling of 
the continuous or manifold paper forms and are provided in both unidirectional 
and bidirectional versions. 


-Mechanical Front Feeder: This device also mounts on top of the Model 630. It 
is intended for use with difficult, multipart forms and the heavier ledger card 
stocks. 


-Bottom Feed: The Model 630 can be configured for feeding continuous or 
manifold forms up thru the bottom of the machine. It must be used with either 
a pin feed platen or a forms tractor. 
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SPECIAL CONSIDERATIONS 


Cleaning Print Wheels 


Print Wheels used with carbon ribbons seldom need cleaning. Both Plastic Print 
Wheels and Metal Print Wheels used with cloth ribbons will require an 
occasional cleaning. 


Remove the print wheel and clean with toluene or naphtha* and a soft brush or 
wiper. DO NOT clean with water. DO NOT get solvent on the hub or damper 
ring (metal wheels). Be careful not bend the "spokes". 


Changing Ribbons During Operation 


As outlined on page 10-9, the Model 630 will stop printing, the RIBBON/PAPER 
light will appear, and the alarm will sound upon reaching the end of a carbon 
ribbon. Should this happen during receipt and print out of data from a host 
system, the operator should open the access cover, replace the ribbon cartridge 
as described, close the access cover, and then touch the Control Panel RESET 
switch to resume printing. 


Cleaning The Print Hammer 


Remove the print wheel and ribbon cartridge as described. Locate the movable 
print hammer inside its guide, as shown on page 10-8. Push the hammer out to 
the rear, to expose as much of the head as possible. Use toluene or naphtha* 
and a wiper or brush to remove any accumulated ink or other substances, and 
wipe dry. 


* Toluene and naphtha are available at most drug stores. 


—e 90% isopropyl alcohol may be used as a solvent for cleaning the print 


hammer. 
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Setting The Switches Under The Access Cover (left to right) 


The 630 Printer has been factory preset to the proper switch positions for use with a 
Xerox 820 Information Processor. For use with other print wheels, the available 
setting positions are as follows: 


1. Print Wheel Select Switch. Set this switch to match the particular type of print 
wheel being used. This ensures your text will print correctly and prevents 
possible print wheel damage or excessive wear. 


PRINT WHEEL SELECT: 





QO: 88 Metal 

23 92 Metal 

33 96 Metal 

4s 96D Metal 
> APL Metal 
63 APL Plastic 
73 Plastic 
1,8,9 Optional 


2. Spacing Select Switch. This switch selects the horizontal spacing for character 
printout. Set this switch to | for 10 Pitch PWS or 2 for 12 Pitch PWS. 


| 
| 
0: Proportional | 
| ls 10 
Zz 12 
3: 15 | 
4-9: Self Test 
For use with the Xerox 820 Information Processor in WP, the switches to the right of : 
Print Wheel and Spacing switches should be positioned toward the front of the 
printer, except for the BAUD switch marked 120. It should be positioned toward the 
back of the printer. | 
| 
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Setting The Operating Switches 


These six switches are located in the right-hand area of the control panel where they 
are accessible to the operator with all covers on the machine. These are membrance 
type momentary action switches actuated by a touch of the finger. 


L. 


RESET Switch. This switch will restore the Model 630 to normal operating 
status following a printer check or an error condition, and clears all error 
indicators. 


SCROLL Switch. Touching this switch advances the paper a small amount to 
give the operator a clear view of the last printed line. The paper is 
automatically returned to the last printing position when the switch is released. 


LF Switch. Touching this switch initiates a single or a double line feed 
operation, as selected by the DOUBLE L.F. MODE SWITCH. Action is repeated 
if the switch is held activated longer than 600msec. A line feed code will not 
be transmitted. 


FF Switch. Touching this switch initiates a form feed to the next top-of-form 


position. A form feed code is not transmitted. 


HERE IS Switch. Touching this switch causes a special "Here Is. ." message 


of up to 31 characters to be transmitted over the communications link when 
Operating in remote ASCII mode with the fully featured HPROS5 option 
installed. This is not used with the Xerox 820 Information Processor. 


BREAK Switch. Touching this switch causes a Break (250msec space) to be 


transmitted over the communications link when operating in remote mode. 


(Audio Alarm). This device buzzes briefly to indicate the occurrence of various 
errors or operating conditions. 
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Reading The Control Panel Indicators (left to right) 


l. 
2. 


POWER. Indicates that AC power is applied to the Model 630. 


PRINT CHK*. Indicates that a print operation has been called for while the 
printer is in a "check" condition. A check condition occurs when a print wheel 
or Carriage movement command has been received but cannot be successfully 
completed due to a malfunction. This condition disables the Model 630 until a 
restore sequences clears the check condition. 


RESET. Note that if the problem causing the check condition has not been 
corrected when a restore sequence has been initiated, the check will reappear 
as soon as printing is attempted. 





PARITY. Indicates detection of any of the following types of error: 


-Incorrect parity sensed on received character. 
-A framing error (no stop bit) detected on a received non-break character. 
-A serial data character detected with an excess number of bits. 


When a parity error is detected, a DEL character is substituted for the 
erroneous character. 


This indicator functions only if the PARITY ENABLE switch (under the access 
cover) is ON. 


OVFL*. Indicates that the Model 630's print input memory (buffer) is too full 
(has overflowed). Protocol has not been used properly. 


RIBBON/PAPER*. Indicates end of ribbon has been reached or that the printer 
is out of paper, and printing has been attempted. 


COVER*. Indicates that printing was attempted with the sound cover open. 


* - These errors cause a Break to be transmitted when the Model 630 is in 
Remote mode if DC1/DC3 protocol has not been selected. 
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SPECIFICATIONS 


Print Speed: Up to 40 characters per second with metalized print wheels. 


Character Set: 8&8, 92 or 96 printable characters per print wheel. Switch selectable 
program support for APL and all ENGLISH language print wheels. 


Print Wheels: 


Metal -88 character Xerox 
-96 character Diablo and Xerox 
Plastic -96 character Diablo 


Character Spacing: 10 and 12 pitch. 


Column Spacing: 1/120 inch (.21mm) minimum. 


Print Line: 13.2 inches (335.3mm) 
132 columns 10 pitch 
158 columns 12 pitch 
198 columns 15 pitch 


Paper Width: 16.53 inches (419.9mm) maximum 
- friction feed without Top Paper Out switch. 
16.00 inches (406.4mm) maximum 
- friction feed with Top Paper Out switch. 
15.25 inches (387.4mm) maximum 
full width with optional forms tractor (14.75 inches/-374.7mm between holes). 3.25 
inches (82.55mm) minimum with forms tractor (2.75 inches/69.85mm between holes). 


Carriage Speed: 400msec maximum for 13.1 inches (332.77mm) of motion. 
Tabulation: Left or right. 
Line Spacing: 1/48 inch (.53mm) minimum. 


Paper Feed: Bidirectional, except with unidirectional forms tractor and uni-direc- 
tional pin feed platen. 


Paper Feed Speed: 4 inches (101.6mm) per second plus 40msec (typical) settling delay 
time. 
Sensors: End of ribbon, top paper out, and cover open. 
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Paper Thickness: 


.000 - .101 inch (.254mm) at low setting (1-3 part forms) 
010 - .027 inch (.254 - .686mm) at high setting (4-6 part form). 


f~ 


Other Features: Self-test; host program control thru escape sequences; data 
receive/transmit speed selection. 


Power Requirements: Strappable for operation from nominal 100, 120, 220 or 240 
volt (+10%/-15%) AC inputs, 49-61 Hz. 350W maximum power consumption. Factory 
preset for 120 VAC. 


CHECK YOUR MODEL 630's SERIAL PLATE FOR PROPER INPUT POWER. 
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FORMS TRACTORS 


i The unidirectional and bidirectional forms tractors are very similar except the 
unidirectional does not have the reverse drive sprockets required for bidirectional 
paper feeding. 


Unidirectional Forms Tractor - This unit mounts on top of the printer cover 
where it engages the platen shaft for alignment and drive. It requires use of a 
friction feed platen. It is adjustable to any paper width from 2-3/4" (69.85mm) 
to 14-1/2" (368.3mm) maximum as measured between the pin feed drive holes. 


Bidirectional Forms Tractor - This unit mounts on top of the printer cover 
where it engages the platen shaft for alignment and drive. It requires use of a 
friction feed platen. It is adjustable to any paper width from 2-3/4' \69.85mm) 
to 14-1/2" (368.3mm) maximum as measured between the pin feed drive holes. 
It also features both forward and reverse pin feed paper drives to enable 
feeding paper in either direction. 
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Forms Tractor Installation 


Note: 


1) 
2) 


3) 


4) 


If your Model 630 has a sound panel, it must be the special sound panel 
designed for use with the forms tractors. 


If you have one, swing the sound panel forward to its open position. 


Pull the paper release lever and paper bail forward toward the front of 
the Model 630 (see Picture, page 10-7). 


Holding the forms tractor at both ends, depress the two latch release 
levers on the tractor and lower it onto the platen shaft (see Picture, page 
10-21). As the tractor is being lowered, guide the paper release actuator 
fork on the tractor over the paper release lever on the Model 630. 


Release the latch levers to clamp the tractor assembly onto the platen 
shaft. Check to see that both ends of the tractor are firmly latched. 


a) 


b) 


Bidirectional forms tractors: Swing thé paper support rack forward 
then backward to make sure the paper release lever stays inside the 
release actuator fork. If the paper release lever slips out, remove 
the forms tractor and repeat steps 2 through 4 of this installation 
procedure. 


Unidirectional forms tractors: The unidirectional tractor is equipped 
with adjustable supports. Adjust these to hold the back of the tractor 
to its forward position, and check to see that the paper release lever 
on the Model 630 snaps in its backward position. Swing the paper 
support rack back to its normal position; the paper release lever 
should be pulled to its forward position. This releases the paper 
tension, which is necessary when operating with the forms tractor. 


Forms Tractor Removal 


1) 
2) 
3) 


Remove any paper from the forms tractor. 


Swing the sound panel forward. 


Depress the two latch release levers (see Picture, page 10-21) and lift the 
tractor straight up. 
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REVERSE DRIVE ASSEMBLY 


PAPER RACK LATCH RELEASE 






LATCH RELEASE 


PAPER RELEASE 
ACTUATOR FORK 


PLATEN CLAMPS 


PAPER FEED ASSEMBLY 
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Loading Paper into the Bidirectional Forms Tractor 


To adapt the following procedure to a unidirectional tractor, simply disregard the 
steps relating solely to the reverse drive assemblies. 


1) 
2) 


If you have one, swing the sound panel open. 

Adjust the two pin feed assemblies to the appropriate form width by 
loosening the feed assembly lock levers and sliding the feed assemblies to 
the left or right as necessary. 


Note: The two feed assemblies on the bidirectional forms tractor each consist of a 
pin feed forward drive belt and a reverse drive sprocket joined together by a metal 


bracket. 


The unidirectional forms tractor is equipped only with the forward drive 


belt assemblies. 


3) 


4) 
5) 


6) 


7) 


8) 


9) 


10) 


11) 


12) 


Swing the paper support rack on the tractor to its forward position. This 
allows convenient access for engaging the paper onto the reverse drive 
sprockets; it also moves the pressure release lever backward so the platen 
will be able to grip the leading edge of the paper and pull it around to the 
forward drive assemblies. 


Open the gates on the reverse and forward drive assemblies. 


Bring the leading edge of the continuous form paper up over the rear of 
the Model 630 and hook the pin feed holes along each side of the paper 
onto the feed pins on the reverse drive sprockets. (Be certain that the 
paper is aligned straight on the sprockets.) Close the gates over the 
reverse drive sprockets to hold the paper in place on the feed pins. 


Slowly rotate the platen to feed the leading edge of the paper down 
behind the paper bar, down around and then up in front of the platen. 


Swing the paper rack back. This moves the paper release lever on the 
printer to release the grip of the platen on the paper. 


Grasp the leading edge of the paper and pull it up while manually turning 
the platen until the leading edge is above the forward drive assemblies on 
the tractor. 


While gently creating tension on the paper by pulling up on the leading 
edge, fit the side holes in the paper onto the feed pins of the forward 
drive belts. Close the gates to hold the paper in place on the feed pins. 
Be certain that the paper is aligned straight. 


Move the paper bail back toward the platen. (The bail will be held away 
from the platen slightly; this is proper when operating with the forms 
tractor.) 


Rotate the platen 2 or 3 turns forward and backward to check that the 
paper is feeding properly through the drive assemblies. 


Close the sound panel. 
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--INTRODUCTION— 


The XEROX 820 system monitor is the basic control program for the single-board 
computer. It begins execution when the computer is first turned on, or whenever 
the reset button is pressed, and resides in the top 4K of memory. 


The monitor provides two essential functions for the system. It is the initial 
software level of the computer and it contains the routines that initialize and 
control all the basic system input/output resources. The "front panel" functions of 
the monitor include commands to display and alter the contents of memory and I/O 
ports, to begin execution at a given address, and to bootstrap programs from disk. 
The basic I/O functions of monitor provide driving routines for the built-in CRT 
display and keyboard input, and the floppy disk controller. In this capacity the 
monitor is always active, even when application programs like the CP/M disk 
operating system have control of the CPU. 


The following sections of this manual will explain how to use the console monitor 
commands, what facilities are provided by the resident I/O handlers, and how to 
interface applications programs to the monitor. 


XEROX 820 MONITOR COMMAND SUMMARY 


The Xerox 820 monitor enters the command mode after it has initialized the 
system following a power-on or a reset. The following sign-on message is displayed 
on the console output device as an indication that the monitor is ready to accept 
commands. 


Ve we Pe EROK BLO 5 Ss 
Enter A for BOOT 
Enter T for TYPEWRITER 


% 


Commands consist of a single character command name and zero to three 
hexadecimal numeric parameters separated by commas or spaces. The command 
line may be entered using upper case or lower case letters. A carriage return is 
used as the terminator. Errors within a line can be corrected by typing control-H 
to delete the last character or control-X to delete the entire line. If a line is 
entered with an unknown command name, an invalid number or parameters or an 
out-of-range parameter, an error message will be displayed and the command will 
not be executed. 


The user may wish to halt long running commands like the memory dump before 
they are finished. This can be done by typing carriage return while the command is 
doing output. Output can also be frozen temporarily and then re-started by typing 
repeatedly on the space bar. 


The following table summarizes the monitor's command set. The items enclosed in 
angle brackets represent the numeric parameters expected by the command A 
detailed description of each command is provided in the following pages. 
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command format 

d(ump) Lee D (start), (end) 

m(emory) ... M (address) 

t(est) ark X (start), (end) 

f (ill) sibs F (start), (end), (constant) 
c(opy) ais C (source_start), (source_end), (dest_start) 
g(oto) wwe G (address) 

r(ead) we R (unit), (track), (sector) 
a(boot) or A(boot) from A drive 
t(ypewriter) .. T 

i(nput) ‘are I (port) 

o(utput) ... O (port), (data) 


NOTE: All of the Monitor parameters are hexadecimal. 
1) DUMP COMMAND 


The dump command outputs a tabular display of the contents of memory in 
hexadecimal and ASCII representation. Each display line has the following 
format: 


AAA DD DD DD DD DD DD DD DD DD DD DD DD DD DD DD pb cccccCapy 


where AAAA is the starting memory address of the line in hexadecimal, the 
DD's are the hex values of the 16 bytes of data starting at location AAAA, 
and the C's are the ASCII characters equivalent to each data byte. Bytes less 
than 20 hex are replaced in the ASCII portion of the dump by period. 


The dump command accepts zero, one or two address parameters. If two 
addresses are specified, the block of memory between those two locations 
will be dispayed. Entering only one address will display 256 bytes of memory 
starting at the specified location. Typing 'D' with no parameters will cause 
the routine to display the 256 byte block of memory starting at the last 
address displayed by the dump command. 
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2) 


3) 


+) 


MEMORY COMMAND 


The memory examine/change command allows the contents of individual 
memory locations to be read from and written into using the monitor. This 
command accepts one parameter representing the memory address at which 
to begin examining data. The display format is as follows: 


AAAA DD _ 


where AAAA is the current memory address and DD is the hexadecimal value 
of the data in that location. After displaying the contents of a memory 
location, the routine waits for one of the following items to be input from the 
console. 


re) Typing a carriage return will cause the routine to display the data at 
the next memory location, with no modification of content. 


O Typing a minus sign will have a similar effect, except the address is 
decremented instead of incremental. 


Oo Typing a two digit hexadecimal number will cause that number to be 
stored at the displayed address. The new data is stored as soon as the 
second digit is entered, with no terminating character required. 


O Typing any character other than carriage return, a minus sign or a 
hexadecimal digit will cause the command to terminate. 


TEST COMMAND 


This command allows the user to test memory for errors caused by defective 
16K memory chips, solder bridges and various other problems. Any portion of 
memory may be tested except the area reserved for the monitor (F000 to 
FFFF hex). Two parameters are required from the user; the starting address 
and ending address of the memory block to be tested. Only the high order 8 
bits of the addresses entered are actually used however, due to a charac- 
teristic of the test algorithm begin employed. If no errors occur, the test 
routine will output a plus sign every time a test pass is done. A total of 256 
plus signs must be output for all possible test patterns to have been tried. 
When errors are detected an error line will be output in the following format: 


AAAA DD should=XX 


where AAAA is the address of a location that fails to test, DD is the data 
read back from the location, and XX is the test pattern that was written 
there. 


FILL COMMAND 


The fill command allows blocks of memory to be filled with a fixed data 
constant. Three parameters are required in the command line; a starting 
memory address, an ending address and a fill constant. Each location in the 
specified block of memory has the constant written into it and then read back 
again to check for memory errors. An error line like the one described for 
the 'X' command is printed for any locations that fail to verify. 
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5) 


8) 


9) 





COPY COMMAND 


The copy command allows blocks of data to be moved around in memory. 
Three parameters are required in the command line; a starting memory 
address, an ending address, and a destination address. The contents of the 
block of memory bounded by the first two addresses is copied to the block 
Starting at the third address. As with the fill command, a test is made to 
verify that each byte of the destination block, when read back, is the same as 
the corresponding byte in source block. 


GO TO COMMAND 


The goto command allows control of the CPU to be passed to another 
program by the monitor. This command requires a single parameter from the 
user representing the address at which to begin execution. The monitor 
actually passes control to the specified location by executing a CALL 
instruction. This makes it possible for the external routine to return to the 
monitor by doing a RET, assuming it does not re-load the stack pointer and 
loose the return address to the monitor. 


READ COMMAND 


The read command allows individual disk sectors to be read into memory and 
displayed on the console. Three parameters are required; a drive unit number 
(range 0 to 1), a track number (range 0 to 27 for 5.25" disks or range 0 to 4C 
for 8" disks) and a sector number (range | to 12 for 5.25" disks or range 1 to 
1A for 8" disks). The command routine performs a drive select, track seek 
and sector read sequence using the supplied parameters. If no errors occur, 
the contents of the input buffer will be dumped out the 'D' command format. 
In the event of a disk error, a diagnostic message will be printed in the 
following format: 


disk error XX UAA TBB SCC 


where XX represents the 1771 disk controller error status code, AA is the 
unit number, BB is the track number, and CC is the sector number. The error 
code is composed of eight bits of status information as described in the table 
below: 


bit read/write seek/restore/select 
7 drive not ready drive not ready 
6 write protected unused 
5 write fault unused 
> record not found seek error 
2 crc error crc error 
2 lost data cannot restore 
l unused unused 
0 always=1 always=0 


The least significant bit (LSB) of the error code indicates which of the above 
sets of error conditions is applicable. If the LSB=1 the disk error was 
generated by a read or write operation, otherwise it was caused by a seek, 
restore, or select operation. 
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10) 


11) 


12) 


13) 


BOOT COMMAND 


The boot command command is used to load and begin execution of a one 
sector long bootstrap loader from the first sector on drive unit zero. The 
most common use of this command will be to boot up the CP/M disk 
operating system, although it is not necessarily restricted to this purpose 
only. 


The boot works by reading the contents of track 0, sector 1 into memory at 
location 80 hex and the jumping to that address to start execution of the code 
just read in. Normally the routine on sector | will be a small loader that in 
turn reads in a larger program such as the operating system. This two level 
bootstrap process makes the boot command more application independent. 
The only requirements are that the first sector of the boot diskette be 
reserved for a loader and that the bottom 256 bytes of memory are not 
written over by the program being loaded. 


TYPEWRITER COMMAND 


This command allows the XEROX 820 to be used as a standard electronic 
typewriter. All key strokes will be typed directly on the attached printer in a 
direct print mode, without displaying any typed information on the screen. 


INPUT COMMAND 


This command allows the contents of input ports to be read from using the 
monitor. It operates very much like the memory examine command, except 
that input ports are being examined instead of memory locations. A single 
parameter representing a port number is expected in the command line. The 
contents of adjacent ports can then be examined by typing carriage return or 
a minus sign as in the 'M' command. Typing any other key will cause the 
routine to terminate. 


OUTPUT COMMAND 


The output command is provided to allow output ports to be written to using 
the monitor. Two parameters are expected in the command line; a port 
number and a data byte to be output to that port. Both parameters should be 
between 0 and FF hex. After outputting the specified data to the port, this 
routine simply returns to the monitor instead of stepping to the next location 
like the input command. This makes it possible to use the output command to 
initialize Z-80 peripheral devices like the SIO, PIO and CTC. 
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MONITOR RESIDENT I/O DRIVER FUNCTIONS 


This section describes the facilities available in the XEROX 820 monitor for 
controlling the input/ouput resources of the XEROX 820 single-board computer. 


1) 


2) 


INTERRUPT PROCESSING 


The XEROX 820 monitor takes advantage of the powerful interrupt handling 
capabilities of the Z-80 microprocessor. Interrupts are utilized in the I/O 
drivers for the console keyboard input, the real-time clock and the floppy 
disk controller. All necessary initialization tasks and interrupt service 
routines for these devices are contained in the monitor. 


For the most part, the operation of the interrupt mechanism should be 
transparent to most applications programs that will run under XEROX 820. A 
few precautions must be taken however, to insure that user written software 
does not adversely effect the operation of the system. The following list 
describes the major hazards to the interrupt system; 


O Interrupts should not be disabled permanently by user code, as this will 
lock-up the console input and real-time-clock routines. 


O The Z-80 'I' register should never be altered. Doing so is GUARAN- 
TEED to crash the system. 


O The CPU operates in Z-80 interrupt mode 2 and should not be switched 
to either of the other two interrupt modes. 


Oo Adequate stack space must be reserved in user programs to allow at 
least one level of stack for interrupt return addresses. Use of the stack 
pointer for 'trick' programming purposes is highly discouraged for the 
same reason. 


The monitor initializes the Z-80 'I' register to point to the system interrupt 
vector table at location FF00 to FFIF hex. This table contains pre-assigned 
vector locations for all the peripheral devices on XEROX 820, including those 
that are not used by any built-in functions in XEROX 820. The devices that 
are not currently used include SIO channel A, the general purpose PIO and 
CTC channels 0 and |. These ports can be initialized and used as needed 
without affecting the overall system operation. Consult .the monitor 
variables table at the end of this manual for the vector addresses. 


MEMORY MAPPED VIDEO DISPLAY 


The XEROX 820 single-board computer is equipped with a built-in 80 charac- 
ter by 24 line CRT display controller, for use with an external video monitor 
as the system. console output device. The refresh memory for the CRT is 
bank switchable from the system's 64K byte memory space and includes a 
hardware address translation circuit for high speed scrolling. 


The XEROX 820 monitor contains an output driver routine for the CRT that 


emulates the characteristics of a typical stand-alone video terminal. An opera- 
tional summary of the CRT driver is given on the next page. 
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CODE KEY NAME EFFECT 

00 @ NUL - NONE 

01 A -SOH - NONE 

02 B  STX - NONE 

03 Ci ry -ETX - NONE 

04 D  EOT - NONE 

05 E _ENQ - NONE 

06 F ACK - NONE 

07 G \ SHEL - NONE 

08 H BS - BACKSPACE OR CURSOR LEFT 
09 I HT - HORIZONTAL TAB 

OA : LF - LINEFEED OR CURSOR DOWN 
OB K VT - CURSOR UP 

oC L FF - CURSOR RIGHT 

0D M CR - CARRIAGE RETURN 

OE N so - NONE 

OF Pp 3=oSI - NONE 

10 P DLE NONE 

11 Q DC! CLEAR TO END OF SCREEN 
12 R  DC2 NONE 

13 S DC3 NONE 

14 T DCs NONE 

15 U  NAK NONE 

16 Vv SYN NONE 

17 W ETB NONE 

18 X CAN CLEAR TO END OF LINE 

19 Y EM NONE 

1A Z SUB CLEAR SCREEN 

1B ESC ESCAPE SEQUENCE 

1C FS NONE 

1D GS NONE 

1E RS HOME CURSOR 

IF VS DISPLAY CONTROL CHARACTER 


All character codes between 20 and 7F hex are directly displayable on 
the screen. Characters are formed in a 5x7 dot matrix. 


New characters are stored on the screen at the location occupied by the 
cursor. The cursor is then moved one place to the right. 


If the cursor must appear at a screen position occupied by a non-blank 
character, the presence of the cursor will be indicated by making the 
overlayed character blink on and off. 


If the displayable character is output when the cursor is in the right- 
most column of the screen, an automatic carriage return and linefeed is 
generated afterwards. 


If a linefeed in output when the cursor is on the bottom line of the 


screen, the entire display is scrolled up one line and a new blank line is 
created on the bottom. 


All character codes between 00 and IF hex are interpreted as control 
characters. Only 12 of these codes have some effect on the CRT 
display, and are described in the table below. The remaining 20 are 
treated as nulls. 
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Backspace: 


Moves the cursor to the next column to the left. If the cursor is in the leftmost 
column of the screen, this character has no effect. 


Tab: 


Moves the cursor right to the next tab stop. The tab stops are fixed at every 
eighth column, starting from the left. 


Linefeed: 


Moves the cursor down one line on the screen. If the cursor is the bottom-most 
line, the screen is scrolled up and a blank line is created on the bottom. The top 
line is lost. 

Cursor Up: 

Moves the cursor up one line on the screen. If the cursor is on the top of the 
screen it rolls around to the bottom. 

Cursor Right: 


Moves the cursor to the next column to the right. If the cursor is in the rightmost 
column, there is no effect. 


Carrier Return: 
Moves the cursor to the leftmost column of the screen. 
Clear to EOS: 


Clears the contents of the screen from the current cursor position to the end of the 
bottom line. 


Clear to EOL: 


Clears the contents of the line the cursor is on, from the cursor position to the end 
of the line. 


Clear Screen: 


Clears the entire screen regardless of the current cursor position and places the 
cursor in the top left corner of the screen. Also re-initializes the CRT driver 
subroutine. 


Escape: 


Used to initiate an XY cursor positioning sequence. The cursor can be moved to an 
arbitrary location on the screen by outputting a 4 character sequence composed of 
1) escape, 2) equals sign, 3) row# character and 4) column# character. The 
row/column number characters are formed by taking the desired row# (range=0 to 
23) or column# (range=0 to 79) and adding 20 hex (32 decimal) to it. 


Home Cursor: 


Moves the cursor to the top left corner of the screen, without altering any 
characters on the display. 


Display CC's: 


Functions as a prefix character to force the output of symbols in the character 
generator that corresponds to ASCII control characters. The next character output 
to the CRT after outputting a 1F hex will be displayed on the screen regardless of 
ms numeric value. If multiple symbols are to be displayed, 1F must precede each 
character. 
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DISPLAY CHARACTER CODES 


This table shows the code for each character to be displayed by the XEROX 820. 
Each character is defined by a unique eight bit code which is represented by a 
hexadecimal code 'XY' where X represents the 4 most significant bits of the code 
and Y represents the 4 least significant bits of the code. 


There are a total of 128 characters in the font se t. Therefore, Y represents a 
hexadecimal number from @ to F, and X represents a hexadecimal number from @to 
7. Therefore, the complete font set is defined by codes from 99 to 7F. If the most 
significant bit of the eight bit code is set to 'l', then the complete font set is 
duplicated with the blink attribute set. The blinking set of characters is then 
defined by codes from 89 to FF. 
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KEY STATION NUMBERING 


BBE 
BRR 
= |[B BIR) 
BREE 
SEE 


SYSTEM COMPONENTS 


10-32 


KEY CODES 





KEY NAME KEY # UNSHIFTEDSHIFTED CONTROL 
HELP 01 1E 1E 9E 
| 02 31 21 91 
2 03 32 40 92 
3 04 33 23 93 
4 05 34 24 94 
5 06 35 25 95 
6 07 36 5E 96 
7 08 37 26 97 
8 09 38 2A 98 
9 10 39 28 99 
0 11 30 29 90 
MINUS 12 2D 5F IF 
EQUAL 13 3D 2B 9A 
BACKSPACE 14 08 08 88 
DELETE 15 7F 7F FF 
- (PAD) 16 2D 2D AD 
7 (PAD) 17 37 37 B7 
8 (PAD) 18 38 38 B8 
9 (PAD) 19 39 39 B9 
TAB 20 09 09 89 
Q 21 7h 51 id 
W 22 77 57 17 
E 23 65 45 05 
R 24 72 52 12 
T 25 74 54 14 
Y 26 79 59 19 
U 27 75 55 15 
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KEY NAME 


oro Oo 


ESC 

+ (PAD) 
4 (PAD) 
5 (PAD) 
6 (PAD) 


ae 
O 
OQ 
A 


Pek eee a a 


SEMICOLON 
APOSTROPHE 
RETURN 
LINEFEED 

UP ARROW 

1 (PAD) 

2 (PAD) 


KEY # UNSHIFTEDSHIFTED CONTROL 


28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
bl 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 


Key Codes 
(continued) 


69 
6F 
70 
DB 
ID 
IB 
2B 
34 


10-34 


49 
uF 
50 
7B 
7D 
1B 
2B 
34 
35 
36 

FUNCTION KEY 
41 
53 
bl 
46 
47 
48 
LA 
4B 
uC 
3A 
22 
OD 
OA 
01 
3] 
32 
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09 
OF 
10 
IB 
ID 
9B 
AB 
B4 


Key Codes 
(continued) 
KEY NAME KEY # UNSHIFTEDSHIFTED CONTROL 
3 (PAD) 55 33 33 B3 
L SHIFT 56 --- FUNCTION KEY --- 
Z 57 7A DA 1A 
X 58 78 58 18 
& 59 63 43 03 
V 60 76 56 16 
B 61 62 42 02 
N 62 6E 4E OE 
m M 63 6D 4D OD 
COMMA 64 2C 3C IC 
PERIOD 65 2E i 7C 
SLASH 66 2F 3F 3C 
R. SHIFT 67 --- FUNCTION KEY --- 
L. ARROW 68 04 04 84 
D. ARROW 69 02 02 82 
R. ARROW 70 03 03 83 
0 (PAD) 71 30 30 BO 
. (PAD) 72 2E 2E AE 
L. CTRL 73 --- FUNCTION KEY --- 
SPACE BAR 74 20 20 00 
R. CTRL 75 --- FUNCTION KEY --- 
| 
ie | 
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3) 


4) 


PARALLEL KEYBOARD INPUT 


A parallel keyboard interface is provided on XEROX 820 for systems that will 
use the built-in keyboard and CRT display as the console I/O device This 
interface is designed to connect to an ASCII encoded keyboard with 8 bits of 
parallel data and a key-pressed strobe. 


The XEROX 820 monitor contains an interrupt driven input handler for the 
keyboard that maintains a 16 character deep FIFO buffer for input data. This 
makes it possible to do a considerable amount of typing ahead without any 
input characters being lost. If characters are typed while disk access is going 
on, they may be lost because the disk routines lock out all lower priority 
interrupts. Any characters received when the FIFO is full will also be lost. 


FLOPPY DISK CONTROLLER 

The system is equipped with an on-board floppy disk interface capable of 
controlling up to two Shugart compatible 8 inch drives, or two 5%" drives. 
The interface hardware is based on a Western Digital 1771 disk controller 
chip, along with extra TTL support circuitry to provide buffering, drive 
select, head load timing and data separater functions. 

The XEROX 820 monitor contains a complete I/O driver package for the disk 
controller. Linkage to the disk I/O routines in the monitor is provided by a 
set of subroutine entry points described later in this manual. The basic 
functions available are: drive select, restore, seek, track, read sector, and 
write sector. The user can also specify the track-to-track seek stepping rate, 
and the sector record length. 


All disk functions are verified upon completion, with the final status being 
returned in the A register. If the command was executed successfully, then 
A will contain all zeros on return, otherwise it will contain an error status 
byte as described above under the console monitor 'R' command. The disk 
driver routines will attempt to recover from any disk I/O errors that occur, 
so it is generally not necessary for user written programs to try to re-execute 
commands that fail the first time. 


DISK FORMAT 


The XEROX 820 is equipped with two (2) compatible Shugart SA400L (5%") 
drives, or two (8") Shugart SA800 drives. The disks for the SA4O0OL (5%") 
drives are initialized in a CROMEMCO format, and the disks for the SA800 
(8") disks are initialized in an IBM 3740 format. 


A format is divided into three (3) parts, field A, field B, and field C. Field A 
is written at the start of each track known as the preamble. Field B is 
written once for each sector which consists of a gap between sectors, ID 
fields, and a data field. Field C is written at the end of each track and is 
known as a postamble. 
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The XEROX 820 disks are initialized in the following formats : 


Parameter 8" 5M" 
Tracks 77 40 
Sectors 26 18 
Bytes/Sector 128 128 
## of Reserved Track for OS 2 3 
Disk Capacity 241K 81K 
5%" Format 
Number of Hex Value Comment 
Bytes of Bytes 
Field A - 16 rr Preamble on Gap 4A 
4 00 Gap 3 
l FE ID Address Mark 
] XX Track # 
| 00 
1 XX Sector # 
l 00 
*FieldB-+ 1 F7 Generate CRC 
11 FF Gap 2 
6 00 
| FB Data Address Mark 
128 E5 Data Field 'E5' Data 
l F7 Generate CRC 
8 a Gap 8 
Field C - 101 rp Postamble Gap 4B 
8" Format 
Number of Hex Value Comment 
Bytes of Bytes 
Field A - 28 FF Preamble - Write at the 
6 00 start of each track 
] FC 
26 FF 
—~6 00 Gap 3 
| FE ID Address Mark 
l XX Track # 
| 00 
l XX Sector # 
| 00 
*Field B l F7 Generate CRC 
ll FF Gap 2 
6 00 
J FB Data Address Mark 
128 E5 Data Field '5' Data 
l F7 Generate CRC 
27 FF Gap 3 
Field C - 247 FF Postamble Gap 4B 


* Repeated for one (1) number of sectors per track. 
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5) 


6) 


7) 


SERIAL INPUT/OUTPUT 


The XEROX 820 single-board computer has provisions for two completely 
independent RS-232 serial ports that can be used to interface to printers, 
CRT terminals and data communications equipment. 


REAL TIME CLOCK 


The XEROX 820 single board computer has Z-80 CTC device that can be used 
to generate the timebase for interrupt driven timers, real-time clocks, and 
other time keeping functions. The monitor will initialize CTC channels 2 and 
3 to interrupt the processor once a second. Channels 0 and | of the CTC are 
not initialized and can be used for other purposes. 


The one second interrupt from the CTC is utilized by the monitor's disk I/O 
routines to implement the disk motor turn-off function. 


PARALLEL I/O OPTION 


A Z-80 PIO chip has been included on the XEROX 820 for general purpose I/O 
interfacings. This device is completely unused by any built-in functions. 
The PIO contains two independent 8 bit parallel I/O ports that can be used to 
interface to printers, ROM programmers, analog converters, other compu- 
ters, or just about anything else imaginable. Those interested in using the 
PIO should consult the schematic drawings for any needed hardware interfac- 
ing details. Data about programming the PIO can be found in most Z-80 
applications manual. | 
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USER ACCESSIBLE MONITOR ROUTINES AND VARIABLES 


This section gives the locations and calling sequences of the user accessible I/O 
routines in the XEROX 820 monitor. It also describes a number of important 
monitor variables that may need to be accessed by user written programs. 


XEROX 820 subroutines are accessed via a table of JUMP instructions beginning at 
memory location F000 hex. All monitor calls should be made to these entry points, 
since the actual addresses of the routines inside XEROX 820 will vary between 
different releases. Parameter passing conventions for the monitor fall into one of 
two groups. The character oriented I/O routines all pass data using the A register, 
while the disk routines pass parameters in C and HL and return status information 
in A. 


Storage for the monitor's stack and working variable occupies the top 256 bytes of 
memory, from FFOO to FFFF hex. The mode 2 interrupt vector table takes up the 
first 32 bytes of this block and the stack starts at the very top. In between, are 
variables used by the monitor resident I/O drivers and interrupt service routines, 
some of which are described below. Programs should not attempt to write into any 
locations in this block that are not specifically mentioned below. 


1) XEROX 820 SUBROUTINE ENTRY POINTS 


F000 ENTO: JP INIT sXEROX 820 cold start entry 
F003 ENTI: JP PROMPT sXEROX 820 warm start entry 
F006 ENT2: JP CONST sconsole input status test 
F009 ENT 3: JP CONIN sconsole input 

FOOC ENT4: JP CRTOUT smemory-mapped CRToutput 
FOOF ENT5: JP CRTOUT smemory-mapped CRToutput 
FO12 ENT6: JP SIOST sSIO port B input status test 
FOL5 ENT7: JP SIOIN ss1O port B input 

FO18 ENT8: JP SIOOUT sSI1O port B ouput 

FOIB ENT9: JP SELECT sdisk drive select 

FOIE ENT 10: JP HOME srestore to track 0 

FO21 ENT 11: Bh SEEK sseek track 

F024 ENT 12: JP READ sread sector into memory 
F027 ENT 13: JP WRITE swrite sector from memory 
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FUNCTION 
COLD... 


WARM... 


CONST... 


CONIN... 


CONOUT.. 


CRTOUT.. 


SIOST.. 


SIOIN... 


SIOOUT... 


SELECT... 


HOME... 


SEEK ...- 


READ... 


PARAMETERS 


IN: none 
OUT: does not return 


IN: none 
OUT: does not return 


IN: none 
OUT: status ina 


IN: none 
OUT: character in A 


IN: character in A 
OUT: none 


IN: character in A 
OUT: none 


IN: none 
OUT: status in A 


IN: none 
OUT: character in A 


IN: character in A 
OUT: none 


IN: unit number in C 
OUT: status in A 


IN: none 
OUT: status in A 


IN: track number in C 
OUT: status in A 


IN: sector number in C 
buffer pointer in HL 
OUT: status in A 


DESCRIPTION 


Perform cold start initialization of 
XEROX 820 monitor and enter com- 
mand mode. 


Enter XEROX 820 monitor command 
mode with no re-initialization. 


Test for data ready in console input 
FIFO and return status in A. If data 
is available then A=FF, else A=00 
hex. 


Return character from console input 
FIFO in A. If FIFO is empty then 
loop until character is input. 


Output character passed in A to the 
memory mapped CRT display 


Output character passed in A to the 
memory-mapped CRT display. 


Test for received data available from 
SIO channel! B and return status in A. 
if data is available then A=FF, else 
A=00 hex. 


Return received data from SIO 
channel B in A. Loop until data is 
received if none is available on entry. 


Output character passed in A to SIO 
channel B transmit register. 


Select specified drive for future 
restore, seek, read or write 
command. If the drive is not ready, 
then the currently selected drive is 
left on. 


Move read/write head to home 
position at track 0 and verify if it got 
there. 


Move read/write head to specified 
track and verify if it got there. 


Read specified sector on current 
track into memory data buffer. 
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WRITE... IN: sector number inC Write specified sector on current 
buffer pointer in HL Track from memory data buffer. 
OUT: status in A 


2) STORAGE ALLOCATION FOR XEROX 820 VARIABLES 
(INTERRUPT VECTOR TABLE) 


FFOO SIOVO: DEFS2 sSIO port B xmit buffer empty 

FFO2 SIOVI: DEFS2 sSIO port B external/status change 
FFO4 SIOV2: DEFS2 ;SIO port B receive data available 
FF06 SIOV3: DEFS2 sSIO port B special receive condition 
FF08 SIOV4: DEFS2 sSIO port A xmit buffer empty 
FFOASIOV5S: DEFS2 sSIO port A external/status change 
FFOC SIOV6: DEFS2 sSIO port A receive data available 
FFOE SIOV7: DEFS2 sSIO port A special receive condition 


FF10 CTCVO: DEFS2 sCTC channel 0 interrupt 
PPIZ CICVie “DEFSZ sCTC channel! | interrupt 
FF14 CTCV2: DEFS2 sCTC channel 2 interrupt 
FF16 CTCV3: DEFS2 sCTC channel 3 interrupt 


FF18 SYSVA: DEFS2 ssystem PIO port A interrupt 
FFLASYSVB: DEFS2 ssystem PIO port B interrupt 


FFICGENVA: DEFS2 sgeneral purpose PIO port A interrupt 
FFILEGENVB: DEFS2 ;general purpose PIO port B interrupt 


(CONSOLE KEYBOARD INPUT VARIABLES) 
FF20 FIFO: DEFS16 _ ;input data fifo buffer 


FF30 FIFCNT: DEFS1 snumber of characters in FIFO 
FF33 LOCK: DEFS 1 scharacter used for software shift 
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Theory of Operation -—- CENTRAL PROCESSOR 


CLOCK GENERATOR: 


All the system clocks with the exception of the baud clock and the video dot clock 
are generated from a master oscillator operating at 20 Mhz. The 20 Mhz clock is 
scaled by the divide-by-5 section of decade counter to provide 4 Mhz for use in the 
floppy disk data separator. The 2 Mhz clock for the disk controller is generated 
from the 4 Mhz clock by the remaining divide by two section. 


The 2.5 Mhz processor clock is generated by dividing the master 20 Mhz clock by 8 
with binary counter. The column address strobe "CAS", and the address multi- 
plexer control "MUXC", are derived from the 20 Mhz clock. When memory request 
"MREQ" is low and refresh "RFSH" is high generation of "CAS" and "MUXC" is 
enabled. "RFSH" disables the generation of "CAS" and "MUXC" by holding shift 
register reset. This is done to take advantage of the low power row address strobe 
"RAS" only refresh mode of the 16K dynamic RAM. 


RESET CONTROLLER: 


Two types of reset take place on the board. Power on reset is detected and 
conditioned by part of hex schmitt inverter. The pushbutton reset is also 
conditioned by a part of hex schmitt inverter. 


PORT ADDRESS DECODING: 


Octal decoder is used to select the appropriate I/O device based on the binary 
value of the address bits A2, A3, & 4. When A7 is low and "MIR" is high, a low on 
"IORQ" will cause the appropriate output of the decoder to go low, selecting the 
I/O device for a read or write operation. 


PORT 0-3 = CHANNEL A BAUD RATE (WRITE ONLY) 
PORT 4 = SIO CHANNEL A DATA 
PORT 5 = SIO CHANNEL B DATA 
PORT 6 = SIO CHANNEL A CONTROL 
PORT 7 = SIO CHANNEL B CONTROL 
PORT 8 = GP PIO PORT A DATA 
PORT 9 = GP PIO A CONTROL 
PORT A = GP PIO PORT B DATA 
PORT B = GP PIO PORT B CONTROL 
PORT C-F = CHANNEL B BAUD RATE (WRITE ONLY) 
PORT 10 = 1771 STATUS/COMMAND REGISTER 
PORT 11 = 1771 TRACK REGISTER 
PORT 12 = 1771 SECTOR REGISTER 
PORT 13 = 1771 DATA REGISTER 
PORT 14-17 = CRT SCROLL REGISTER (WRITE ONLY) 
PORT 18 = CTC CHANNEL 0 
PORT 19 - CTC CHANNEL 1 
PORT 1A = CTC CHANNEL 2 
PORT 1B = CTC CHANNEL 3 
PORT IC = SYSTEM DATA PORT 
PORT 1D = SYSTEM CONTROL PORT 
PORT IE = KEYBOARD DATA PORT 
2 PORT IF = KEYBOARD CONTROL PORT 
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DISK TRANSFER SYNCHRONIZATION: 


In order to successfully execute the high speed data transfers between the 
processor and the disk controller, the fast Z-80 non maskable interrupt "NMI" 
response was employed. During reads and writes to and from the disk controller, 
the data at memory location 66 hex is retrieved and stored. This location is 
overwritten with a RETURN instruction. After this setup is accomplished the 
processor executes a HALT instruction. When the processor is in a HALT 
condition, a DATA REQUEST (DRQ) or an INTERRUPT REQUEST (IRQ) from the 
disk controller will cause a non-maskable interrupt to be generated. The processor 
then executes the RETURN instruction at 66 hex and returns to transfer the data 
to or from the disk controller. When the 128 byte transfer is complete the old data 
is restored and the processor resumes normal operation. This hardware assistance 
obviated the necessity for a DMA device by eliminating the disk controller "DRQ" 
Status test. 


CRT DISPLAY CONTROLLER 
VIDEO SCROLLING: 


In order to eliminate the delay associated with software scrolling, hardware 
assistance was employed. For ease of understanding, the CRT RAM resides from 
3000 hex to 3FFF hex. Writing into the scroll register adds an offset to the line 
address developed by the line counter. The net effect is similar to the rotation of 
a cylinder whose axis is horizontal and perpendicular to the line of shift. The 
amount of rotation is determined by the magnitude of the number contained in the 
scroll register. For instance, an offset of zero puts the data at location 3000 hex 
(of the CRT memory) at the bottom of the screen. If the offset was one, the data 
at 3000 hex would be displayed on the line next to the bottom. An offset of 
seventeen hex (23 decimal) puts the data at location 3000 hex at the top of the 
screen. 


VIDEO RAM ADDRESSING: 


If the processor is doing a read or write to video RAM "CRTCE" (CRT memory 
access enable) will go low. When "CRTCE" goes low, the address from the 
processor is selected instead of the address generated by the counter chain. This 
gives the processor access to the video RAM for read or write operations.CPU 
ACCESS OF VIDEO RAM: 


During read or write operations involving the video RAM and the CPU, "CRTCE" 
will go low. When "CRTCE" goes low the processor address bus is selected as the 
address source for the video RAM. A low on"CRTCE" is also used as a term in the 
direction control logic for data buss access. During a processor read operation, 
data from the video RAM at the specified address is allowed onto the processor 
data bus. During a processor write operation, data from the processor is written to 
the video RAM at the specified address. 
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VIDEO GENERATION: 


While in the display mode, ASCII data from the video RAM and scan address data 
are used to select the proper dot patterns from the character generator. The 
character generator contains | Font pattern of 128 characters. 


DISPLAY BLANKING: 


The display is blanked during horizontal retrace, vertical retrace, CPU access, and 
decode of scan counts 8 & 9. Blanking is accomplished by disabling the character 
generator. 


64 K RAM AND BANK SWITCHING 
REFRESH: 


During the refresh cycle, the Z-80 places the refresh address on the lower 7 bits of 
the address bus. When this address is stable in the RAM array, th "RFSH" pin on 
the Z-80 goes low. The active low "RFSH" generates a "RAS" on all RAMs. An 
active "RFSH" disables the generation of both "CAS" and "MUXC" . 


BANK SWITCHING: 
Bit 7 of port 1C hex is the bank switch control. When the output is high, the ROMs 


and the CRT display appear in the lower 16K block. When bit 7 of port IC hex is 
low, all the 64K RAM is available to the processor. 


FLOPPY DISK CONTROLLER, SYSTEM PIO, AND CTC 


FLOPPY DISK CONTROLLER: 


The 1771 Disk Controller performs all the control functions required to interface 
to a floppy disk drive. The only support required by the 1771 is external data 
separation, inverting data bus transceivers, head load timer, and buffering to and 
from the drive(s). : 
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DATA SEPARATOR: 
ti’ 


Presettable counter is used as a timing reference developed by the system clock. 
Raw data coming from the disk drive is used to preload the counter. If the counter 
does not receive a data bit between clocks the counter in effect times out and 
presents the controller with a logic zero. If the counter receives data between 
clocks, the controller will see a logic one on its data input. | 

















f DATA BUS BUFFERING: 


Inverting transceivers adapt the 1771 to the non-inverted Z-80 data bus. During a 
read operation, data from the 1771 is allowed onto the processor's data bus. | 
Otherwise, the processor's data bus always drives the 1771's data inputs. | 


CTC: 


_ The CTC resides at ports 18 hex through 1B hex (see page 10-38). All the inputs 
and outputs associated with the CTC are available to the user. Refer to the 
strapping option section for pin assignments. 


SYSTEM PIO: 


The system PIO resides at ports 1C hex through IF hex. The "A" side of the system | 
PIO controls the floppy disk drive select, bank switching, disk power switching, | 
cf” sensing keyboard data available (for polled keyboard applications), and on un- | 
committed user definable I/O bit. The bit allocations are as follows: | 


BIT 0 = DVSEL 1 
BIT 1 = DVSEL 2 
BIT 2 = SIDE | 
BIT 3 IS USED FOR KEYBOARD DATA AVAILABLE | 
BIT 4 IS 8"/5%" DISK SELECT | 
BIT 5 ASSIGNED FOR FUTURE USE 
‘ BIT 6 CONTROLS DISPLAY CHARACTER SET 
BIT 7 CONTROLS THE BANK SWITCHING (0=RAM) 





| 
| 
| 
The drive select information should be presented to the system PIO in the following | 
manner: | 

| 


read port 1C hex to maintain system status data 

mask off the lower 3 bits 

"or" in the desired drive & side information | 
write the modified data to port 1C hex | 


The "B" side of the system PIO is devoted to the keyboard. The keyboard port is 
eight bits wide and is fully buffered. | 
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GENERAL PURPOSE PIO AND SIO 


The G.P. PIO provides the user with 16 bits of user definable input or output or a 
mix of input and output on nibble boundaries. The G.P. PIO resides at ports 08 hex 
-0B hex. The PIO will support all modes of interrupt supported by the Z-80. For 
detailed programming information refer to the Z-80 PIO data sheet. For 
applications information, refer to the strapping option section. 


SIO: 


The Z-80 SIO supports two full channels of serial I/O with the capability of 
supporting full RS-232 protocol on both channels. In addition, the A side of the SIO 
can provide clocks to synchronous modems or receive clocks from the modem. 


Channel A of the SIO can be configured to interface to a modem or a terminal. 


Refer to the strapping option sheets for detailed instructions. Refer to the SIO 
data sheet for programming information. 


Channel B of the SIO is dedicated for printer operation and has no strapping 
options. 


The "SYNC" pins on both channels of the SIO have been connected to the Rx data 
pins to facilitate baud rate selection. Utilizing this feature, the start bit duration 
can be timed, and the baud rate can be set accordingly. 


BAUD RATE GENERATOR: 


The COM 8116 provides the user with two programmable baud rate generators. 
Channel A baud rate resides at port 00 hex and is write only. Channel B baud rate 


resides at port 0C hex and is also write only. The programming procedure is as 
follows: 


00 hex = 50 Baud 

Ol hex = 75 Baud 

02 hex = 110 Baud 
03 hex = 134.5 Baud 
04 hex = 150 Baud 
05 hex = 300 Baud 

06 hex = 600 Baud 

07 hex = 1200 Baud 
08 hex = 1800 Baud 
09 hex = 2000 Baud 
OA hex = 2400 Baud 
OB hex = 3600 Baud 
OC hex = 4800 Baud 
OD hex = 7200 Baud 
OE hex = 9600 Baud 
OF hex = 19.2 Kbaud 
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INTERRUPT STRUCTURES: 


All the Z-80 family devices on this board are capable of supporting mode 0, 1, and 
2 interrupts. Mode 2 interrupts are used in the monitor delivered with the system. 
The I register in a unmodified system is loaded with OFF hex. The priority chain is 
organized high to low as follows: 


SIO CHANNEL A 

SIO CHANNEL B 
SYSTEM PIO PORT A 
SYSTEM POI PORT B 
GP PIO PORT A 

GP PIO PORT B 

CTC CHANNEL 0 
CTC CHANNEL 1 
CTC CHANNEL 2 
CTC CHANNEL 3 


SYSTEM COMPONENTS 
10-47 








GENERAL PURPOSE PIO STRAPPINGS (311) AND PIN ASSIGNMENTS (38) 


J3 
1 2 
all odd O o port A STROBE 
numbered o o port A READY 
pins are O Oo port A bit 0 
grounded o Oo portA bit | 
Oo Oo portA bit 2 
O Oo port A bit 3 
Jil O o portA bit 4 
] 2 O Oo portA bit 5 
Oo Oo O o port A bit 6 
0 o port B READY polarity fe) Oo portA bit 7 
oS o port B lower direction O o port B READY 
all odd # pins o o port A READY polarity Oo o port B STROBE 
are grounded o oO port A upper direction O o port B bit 0 
O o port B upper direction O Oo port B bit 1 
Oo o port A STROBE polarity O Oo port B bit 2 
Oo o port B STROBE polarity O o port B bit 3 
fe) o port A lower direction O o port B bit 4 
fe) Oo Oo o port B bit 5 
19 20 O oO port B bit 6 
O o port B bit 7 
39 = 40 
CTC STRAPPING AND I/O ASSIGNMENTS (J10) 
J10 
Zz 4 
SYSTEM CLOCKo o CLOCK/TRIGGER 0 
ZC-TOO © 0 CLOCK/TRIGGER 1 
ZC-TO1 o o CLOCK/TRIGGER 2 
ZC-TO2 o o CLOCK/TRIGGER 3 
8 7 


VIDEO OUTPUT CONNECTOR PIN ASSIGNMENTS (37) 


J7 
6 1 
oO 
oO 
6-10 grounded o o_ Vertical Sync 
o o- Horizontal Sync 
0 0 Video 
10 5 
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SERIAL I/O CONNECTOR PIN ASSIGNMENTS CHANNEL A (J4) 
J4 


> 


PROTECTIVE GROUND 
TRANSMIT DATA 
RECEIVE DATA 
REQUEST TO SEND 
CLEAR TO SEND 
DATA SET READY 
PROTECTIVE GROUND 
CARRIER DETECT 


TRANSMIT CLOCK 
RECEIVE CLOCK 


DATA TERMINAL READY 


NOOCQODQOQOOCOOC0O00 = 


—-OddWGOAGDWAGC9O0O0O0 0 = 
Ww 


SERIAL I/O STRAPPING OPTIONS FOR CHANNEL A (J9) 


Only channel A is capable of utilizing baud clocks from an external device or of 
providing baud clocks to an external device. When providing the baud clock to the 
external device the SIO must use the same clock source. 


J9 


(M) RXD to Pin 3 

(T) TXD to Pin 2 

(M) TXD from Pin 2 
(T) RXD from Pin 3 
(M) CTS to Pin 5 

(T) RTS to Pin 4 

(M) RTS from Pin 4 
(T) CTS from Pin 5 
(M) DCD to Pin 8 

(T) DTR to Pin 20 
(M) DTR from Pin 20 
(T) DCD from Pin 8 
Clock supplied to Modem as RX Clock 
Clock supplied to SIO with RX Clock 
Modem supplies SIO with RX Clock 
Clock supplied to SIO with TX Clock 
Modem supplies SIO with TX Clock 
Clock supplied to Modem with TX Clock 


Wwoododododcoddaed0caecndceaengnngaeaedgeeaeegd oO = 
Fooo0o0o0ooaooaoaoa0aoeoaoaoaaoaaaaa0o dN 
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DATA SET READY IS ACTIVE ON BOTH CHANNELS 
Legend 
iM) Indicates modem (Data Commuinications Equipment) function 
(T) Indicates terminal (Data Terminal Equipment) function 


For instance, exercising the (T) strap options will allow communication with a 
modem. Exercising the (M) strap options would allow communication with a 
terminal. 


TXD = Transmitted Data 
RXD = Received Data 

RTS = Request to Send 

CTS = Clear to Send 

DTR = Data Terminal Ready 
DCD = Data Carrier Detect 


SERIAL I/O CONNECTOR PIN ASSIGNMENTS CHANNEL B (J3) 


J3 


—_ 


Ground 

Receive Data 
Transmit Data 
Clear to Send 
Request to Send 
Data Set Ready 
Ground 
Terminal Ready 


Data Carrier Detect 


NOO00C00000000 = 


‘nent © © a © ae © a © a © a © a © a © a © © OO 
wn 
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KEYBOARD CONNECTOR PIN ASSIGNMENTS (J2) 


BIT 0 
BIT 1 
BIT 2 
BIT 3 
BIT 4 
BIT 5 
BIT 6 
BIT 7 
STROBE 


+5 volts 


J2 
1 14 
o Oo 
o oO 
o oO 
o Oo 
o oO 
o Oo Pins 14-25 are all grounded 
o Oo 
6:6 
o oO 
o Oo 
o Oo 
o oO 
Oo 25 
13 


DISK DRIVE CONNECTOR PIN ASSIGNMENTS (J1) 


8/5% Select 
Index 

Select 1 
Select 2 
Side 

HDLD 

Step In 

Step 

Write Data 
Write 

TRK 00 
Write Protect 
Read Data 
Low Current 
Ready 


Jl 


NO 
=) 


Pins 20-37 are all grounded 


Wwoodododcooqgnodceqgnqgqddsd 


—-Odd0d0C0C0D0C O00 000000 = 
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